Short but complete programs

The greatest challenge to any thinker is stating the problem in a way that will allow a solution. - Bertrand Russell

(Note: this page is written by Jon Skeet, from a first person perspective - but if you've been directed here by someone else, chances are they share the same basic views on the topic.)

When newsgroup posters say that something isn't working for them, I often ask them to write a short but complete program that demonstrates the problem. Chances are, that's the reason you're reading this page. I decided that just "a short but complete program that demonstrates the problem" didn't quite cut it in terms of saying exactly what I'm after. In my experience, if you follow the guidelines on this page, you will almost certainly get a good response when you post your question to the relevant newsgroup. The response may be "Oh yes - it looks like there's a bug..." but at least it'll be confirmation. Advanced warning though - if you post an overly long or incomplete program, my only response is likely to be to redirect you to this page rather than trying to turn your posted code into an appropriate short but complete program. You should be able to do it quicker than I can, and it's more in your interests than mine to do so :)

Furthermore, I suspect you'll find that at least half the time, by the time you've written the program, you don't need to ask the question any more. That's certainly what I find. Having problems when programming is nothing new, and all developers, from the newest to the most experienced, will encounter problems. Writing a short but complete program is an excellent way to pin down exactly what that problem is, without the clutter of irrelevant aspects of your program. When you've seen exactly what the problem is, often the answer becomes obvious. If it isn't, then you'll usually find a newsgroup post with only the relevant details gets an answer pretty quickly.

There are times when this approach doesn't work - when it's almost impossible to come up with a short program that reproduces your problem. This can be due to some nasty threading mistakes, or various application domains or assemblies interacting in a particularly horrible way. Those two examples can be boiled down to short but complete programs, usually, but you really need to know the root of the problem first, unfortunately. In those cases, it's still worth writing the short but complete program after you think you've actually solved the problem, just to test whether or not it could have been responsible for it. Perturbing a complicated program can appear to fix things when it's just moved the problem around, but showing that you have at least solved a genuine problem (even if it's not the only one) is a good thing to do. If you're stuck and can't reproduce the problem, it's worth saying so in your newsgroup post, giving as many details as possible about the situation - where the code's running, which user it's running as, etc. That may well be a clue to the reader.

The key criteria for short but complete programs:

They should be short.

Anything which is unnecessary should be removed. This includes unnecessary business logic, GUIs, etc. For instance, in order to ask a question about reflection, you would very rarely need to include anything about a database. Asking a question about a database, you'd rarely need to include a GUI. It's often worth including brief comments, especially if an exception is thrown and the details include the line number - showing which line the exception is thrown on can make the answer obvious to a reader without them having to run the code themselves. If you can get it down to a single short class, or maybe two or three, just post the code: there's very rarely any need for a full VS.NET solution file, for instance, or the binaries that you happened to build on your machine. If you feel the need to supply a zip file, chances are you haven't cut the problem down enough.

Of course, if your problem really does involve a GUI, then it is entirely appropriate to provide a GUI program. However, it is then handy if you avoid using the designer, as it tends to make the code longer and harder to read for no good reason. If you really can't do without the designer, please go through the code it has created and remove all the unnecessary stuff before posting. If you're using C# v2.0 and the designer has created a separate partial class, please incorporate the contents into a single class to make things easier to read.

They should be complete.
Usually a program can be written to demonstrate the problem in a few classes at most - often just a single class is needed. If at all possible, don't require any extra files. For instance, if you're asking about the speed of populating a ListView, even if your original program is populating it from a text file, it's easier for people who might respond to your question if you just populate it with simple data (e.g. "Line number: "+lineNumber). If you really do need to use a database, it's great if you can demonstrate your problem against the sample database which comes with the database system (the Northwind database for SQL Server, for instance). If your problem lies with DataSets and DataTables, you may well not need to have a real database backing the data at all - it's pretty simple to create a DataTable in code and add some data to it.
They should compile.
This goes hand-in-hand with completeness. Someone should be able to cut and paste code directly from the post to a new file, and compile it using csc Test.cs or the equivalent. Make sure your newsreader is posting in plain text, and make sure all the lines of your code are about 76 characters or fewer (so that the code can be quoted a couple of times and still fit properly). Do not just type in code directly and post it without trying to compile (and run) it yourself - you may well make a typo and waste people's time. People who have had their time wasted by a typo are less likely to answer the next time: when someone points out an error in your code and you say, "Oh yes - that's not in my real code," they're likely to get annoyed. If, of course, your problem is that something you expect to compile doesn't compile, ignore this point - but make sure you don't have any extra irrelevant code in there too. If your code is in VB.NET, it's probably worth posting the compilation command line as well, so that it's obvious which assemblies need to be referenced.
They should demonstrate the problem.
A good form of post is to have a short general introduction to the problem, followed by a description of what you expect your program to do, what it actually does, and then the code. Where appropriate, cut and paste the results of the program, rather than typing them in directly.

Posting the program

If you've got a single class (or maybe just two or three) then it's best to post it inline. Make sure that each line is short enough so that it doesn't wrap. Outlook Express has a particularly annoying habit of inerting a blank line between each "real" line of code if you cut and paste directly from Visual Studio. In order to avoid this, cut and paste the code from your IDE into a plain text editor (eg Notepad) and then cut and paste from there into Outlook Express. Just to show you what I mean, here's an example of what a "bad" post can look like:

This is my code which doesn't work. It fails with a NullReferenceException.

using System;


public class Test

{

    static void Main()

    {

        string x = null;

        Console.WriteLine (x.Length);

    }

}

What they meant to post is:

This is my code which doesn't work. It fails with a NullReferenceException.

using System;

public class Test
{
    static void Main()
    {
        string x = null;
        Console.WriteLine (x.Length);
    }
}

Whitespace used judiciously makes things easier to read. A blank line between each real line is hideous though, as you can see!

If there's a lot of code in one class, you might consider using a service like PasteBin to let people browse the code with syntax highlighting without needing to put it all in a post.

If you have lots of files - something which you should try to avoid, but which is occasionally necessary - it's probably worth zipping the files up and attaching the zip file. Don't forget to put some explanatory text in your post though - say what the zip file contains, how to compile it, how to run it, what you expected to see and what you're actually seeing.

Example of a good post

Here's an example of a question someone might post. Note that it is a simple console program, it compiles directly, and there's sufficient extra information provided about the actual question that an answer is easily given:

I have read that C# passes objects by reference. This doesn't seem to be 
the case given the program below. I expected it to print "second", but it
prints "first".
Can anyone explain this behaviour?

using System;

public class Test
{
    static void Main()
    {
        string x = "first";
        ChangeString (x);
        Console.WriteLine (x);
    }
    
    static void ChangeString (string y)
    {
        y = "second";
    }
}

(The answer to the question can be found here, by the way.) Admittedly that's a particularly simple question, but many articles which have been posted with pages and pages of code could have been boiled down to examples nearly as simple as the above.



Back to the main page.