Writing Good Bug Reports

It's not enough to get everyone in the company using FogBugz. You also need to get them using it well. The key here is to teach people to write good bug reports. For starters, every bug report should contain the three essential pieces of information:

• How to make the bug happen

• What happened

• What should have happened

Put that way, it looks easy, right? But if you've ever spent time trying to actually respond to bug reports, you know that writing good bug reports is harder than it looks. People post all sorts of crazy things to bug databases (and that's not even counting spam, which FogBugz fortunately does a good job of weeding out before it gets to you).

When you think you've found a bug, the first step is to record the information about how to reproduce the bug. The key problem here is to include just the necessary information. Determining what's necessary is an art. What you had for breakfast this morning probably doesn't have a bearing on the bug (unless you're testing dietary analysis software). The operating system on your computer and the amount of RAM could have a bearing. The last action you took in the application almost certainly does make a difference.

Whatever information you can collect, please organize it sensibly. Programmers tend to be focused on careful instructions, so step-by-step details are very useful. Figure 1-6 shows a bug with a good set of reproduction steps.

Figure 1-6. A bug report to make a developer happy

Sometimes it's just not possible to come up with good repro steps. Perhaps you used the application for quite a while and it suddenly crashed, and you don't remember what you were doing. In that case, write down everything you remember. Perhaps you thought you had the steps, but they don't always make the bug happen. In that case, record the steps, but please also tell the developer that the bug is intermittent. Otherwise, it'll probably just get closed as not reproducible.

The second piece of information you need to supply is what happened that made you think this was a bug. Did the program destroy all the files on your hard drive? Did Windows expire in the fabled Blue Screen of Death? Did the developers just spell a word wrong on-screen? This information often makes the best title for the bug as well; something like "Shift-Enter fills hard drive with temporary files" is easy to recognize when you're just scanning down a list of titles.

Finally, tell the developer what should have happened instead. "Sausauge should be spelled sausage" will help guide the poor developer who wasn't at the top of his English class. At times you can omit this piece of information because it will be implied by the description of what happened. If you report it as a bug that the program failed to install on a particular operating system, it's a safe bet that you expected it to install. But when in doubt, be explicit.

0 0

Post a comment