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.
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.
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.
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.