A good bug report is one that describes the problem well enough that someone familiar with the project can understand and act on that bug report without talking to the person who wrote it.

When it comes to setting the bar, that’s it. Anything less is simply not good enough.

Any group that develops software needs to be skilled in writing bug reports that can effectively capture the details of a problem in a way that is useful to the rest of the group.

The rest of the group means other developers, project managers, product managers, testers — people who are both technical and non-technical but need to understand the nature and severity of the problem so that they can organize, plan, and take appropriate action.

A good bug report has all of the following:

Title and Description

A descriptive title that contains specific key words and terms to enable categorization.

NOT GOOD: “An application named Finder should not lose my files”
GOOD: “Icons can be placed offscreen, and lost”

A summary of the situation that describes the problem at a high level, in a way that anyone familiar with the project can understand.

NOT GOOD: “Can’t save images.”
GOOD: “Every time I try to save a large image to the photo library, the app crashes.”

Detailed Steps and Expected Behavior

A set of steps to recreate the situation. These should start with launching the app, include any relevant configuration steps, be atomic, be specific, end with the action that causes the problem to be visible.

While these steps may sometimes seem unnecessary, they are very valuable when you want to close the bug. You cannot verify the fix without a specific set of steps. How would you know that this was the workflow that the tester used?

The expected behavior, and why the observed behavior is different. This leads to more Aha! moments than you would imagine. Many of the details left out of the description will appear here.

Priority

The severity of the issue. When this happens, how bad is it? It’s important to be clear on your reasoning as to why this is the worst bug you’ve seen in your lifetime, so that others can understand and support your decision.

The frequency of the issue. How often does this occur? Always? Once? The general nature of a problem is often not enough to characterize that problem. One also needs to know the frequency. I discussed the importance of severity and frequency in an earlier article.

Context

A description of the context in which the problem was found — the specific system, device, or OS, and any relevant configuration options for the test environment.

• build # of the product under development
• type of hardware on which test was run, e.g. iPhone, iPad, Mac
• configuration of hardware, e.g. 8Gb iPhone 3G, 32Gb iPad 3G
• OS version / build # on that hardware
• any special conditions, e.g. on wifi, after low battery warning

At this point, you may be saying to yourself, “That seems like overkill.” Maybe. I doubt it. An extra minute spent adding the above information to a bug report can save hours of engineering time if it keeps someone from investigating the wrong thing, on the wrong device, without knowing that it only happens on the local network with yesterday’s build.

Pictures and Examples

It is incredibly helpful to have images that show UI problems and sample code that demonstrates API problems.

If you’re writing a bug about a user interface issue, take a screenshot or two. Feel free to add circles and arrows that make it clear where the problem is. When you can, show the correct UI and then the problem. That helps everyone more quickly understand the issue.

Likewise, if you’re writing a bug which involves an API, attach a sample project which exhibits the problem. This helps to ensure that the problem is not related to something in your project, and also makes it much easier for your API vendor to investigate.

If you’re submitting bugs to Apple, make sure to send sample code.

You’ll find that bugs that are clear — especially those that provide a test case in the form of a sample project — will get investigated and resolved more quickly.

The Big Picture

The details above also give the people prioritizing work a clear picture of the issue, and enable them to make good decisions about the priority of bug fixes.

It’s good to know that the crasher that Marketing is freaking out about happened only once, on an old build, and on prototype hardware.