Wikipedia:Reference desk/How to ask a software question

The question

When asking for help with software, new programmers often ask questions which nobody could possibly answer. Here is an example:

I am writing a Perl program, but it doesn't work. I am reading in the names but they come out wrong. Is there a solution?

The question is unanswerable for three reasons:

1. readers don't know what the goal is
2. readers don't know what the problem is
3. readers don't have example source code in which to look for the problem

Goal

For readers to know what's going wrong, they must first know what right looks like. Tell readers what you're trying to do.

Let's fix the request so that the goal is stated:

I am writing a Perl program, but it doesn't work. The program should read in a list of names, and then print them in alphabetical order. I am reading in the names but they come out wrong. Is there a solution?

Problem

That's better, but there's still no way for readers to answer the question -- they still don't know what the problem is! You must describe what's going wrong.

Let's fix the request so that the problem is stated:

I am writing a Perl program, but it doesn't work. The program should read in a list of names, and then print them in alphabetical order. I am reading in the names but they come out in the wrong order. In fact, they come out in same order that they started in! Is there a solution?

Example

That's better, but there's still no way for readers to answer the question, since the names could be in the wrong order for many reasons. You must post an example of source code that exhibits the problem behavior.

Let's fix the request to include an example:

I am writing a Perl program, but it doesn't work. The program should read in a list of names, and then print them in alphabetical order. I am reading in the names but they come out in the wrong order. In fact, they come out in same order that they started in! I have posted my code below. Is there a solution?

#!/usr/bin/perl

# Read the names into the @people array
while (<>)
{
    push @people, $_;
}

# Now sort the names
sort @people;

# Now print them out
foreach $person (@people)
{
    print $person;
}

Perfect! Now the question can be answered by anyone who knows Perl. In addition, now that readers can actually see the program, they are able to provide tips to help the questioner solve the problem on their own next time.

Finally, an answer!

Here's a good answer to the question, which would not have been possible when we started:

The problem is on line 10. Unlike the sort() function in some languages, Perl's sort() does not re-order the list "in-place". It actually makes a copy of the list and then sorts and returns that. Changing line 10 to:

   @people = sort @people;

will fix the problem. This is actually a pretty common mistake, and perl will catch it for you if you turn "warnings" on. To do that, change the first line to:

   #!/usr/bin/perl -w

and perl will say:

Useless use of sort in void context at line 10.

which is a little obscure, but at least tells you to look for trouble on that line. Using -Mdiagnostics instead will give you a very long and helpful explanation. -- PerlyGates 22:39, 18 August 2009 (UTC)

External links

• How To Ask Questions The Smart Way - A thorough but long-winded treatise on asking technical questions.
• How do I post a question about code that doesn't work correctly? A C++-oriented checklist for posting good questions.