Nobody likes bugs, least of all programmers. No matter how hard we try to catch them early, some will always escape into circulation. Until computers are smart enough to do what we meant instead of what we said, users are going to keep finding bugs, and we’re going to keep fixing them.

Before a bug is fixed, it needs to be reported. Unfortunately it’s not uncommon to receive incomplete reports. We can spend a lot of time hunting and making guesses, and sometimes that’s enough, but if we can’t figure out the problem it’s pretty hard to fix it. This can be especially unfortunate when the stakes are high, and oddly, this is when it also seems to be the most common.

So what does a bad bug report look like?

The website crashed.

I get this kind of report now and then, even from experienced members of our support teams. I almost always need to send it back to get more information.

If I got this report instead, I wouldn’t (usually) need more information:

When I open the store website I get a 502 Bad Gateway error.

When I’m trying to understand a bug, I need to know four things:

  • How did you encounter the bug? (Steps to Reproduce)
  • What happened? (Actual)
  • What should have happened? (Expected)
  • Where did you encounter the bug? (Location)

Here is another example of a bug that would be hard to figure out:

I can’t delete a user.

It only answers one of the questions (Expected). I might be able to guess what the user tried to do (Steps to Reproduce), but there could be multiple ways to do this. It doesn’t tell me what application was being used (Location) or what happened (Actual). Was there an error message? Did the application close unexpectedly? Did the computer explode in a ball of fire? I can help with most of these, but they all get approached differently.

If you want a gold star, this is a more formal way to report the same bug, and the format I typically use myself:

Steps to Reproduce:
1. Go to the user list
2. Click a user
3. Click delete
* Receive successfully deleted notification
4. Return to user list
Actual:
* User appears in the list
* When I click on the user again, I get the error “User not found”
Expected:
* User does not appear in the list
Location:
* Admin site: https://{someserver}/admin/users

How did you encounter the bug? (Steps to Reproduce)

The first step to fixing a bug is trying to reproduce it. Exact steps can help a lot with this. Sometimes it isn’t enough, but it’s even more helpful when there are other factors involved.

What happened? (Actual)

A detailed, unemotional description of what happened is the most important part of a bug report. If there in an error message, give us the exact text. It may not make sense to you, but this can tell us a lot about what is going on. If possible, copy and paste the exact text of the error. A screenshot can also be really helpful.

Expressions like “crashed” or “failed” or “doesn’t work” sound good, but they don’t tell us what happened. You don’t need to use technical words if you don’t know them, but you should avoid interpreting the information. For example “an error message appeared that said …” is much more helpful than “it failed”.

What should have happened? (Expected)

Sometimes this is obvious. Generally when someone reports an error message we understand they expect not to get an error. Sometimes the expected behavior is not so obvious.

Keep in mind that programmers are trained in programming, and are usually not experts in the fields where our programs are being used. For example, if there’s a problem with the way tax is being calculated in an accounting application, the people looking at the bug may know less than you do on the subject. For technical bugs and miscalculations it can also be helpful to include how you determined the result you expected.

Where did you encounter the bug? (Location)

It’s not always obvious, but sometimes companies have more than one piece of software, or more than one version in circulation.

If you’re using a website, include the URL. If it’s a visual bug, maybe include the browser you’re using, it’s version, and the operating system you’re using it on. If it’s a mobile app, include the kind of phone you have. If the app has a version number include that too.