Writing Great Bug Reports

The most important aspect of a job in software QA isn't having the ability to find great bugs. It's having the ability to describe bugs so that someone else can repeat them. Any software engineer will tell you that you can't fix a bug until you can reproduce it. But many of those same engineers will send your carefully written reports right back with the label "CAN'T REPEAT." After a while, you might start to suspect that they didn't even try to repeat it. The sorry truth is, after sifting through enough of your incomplete or confusing bug reports, many engineers won't try. So what do you do now?

First, make sure that your bug report really is as easy to understand as you think it is. Learn the correct terms to describe your product's features, and use them. Try to communicate exactly what you did to cause the bug to appear. Spell things correctly. And never assume that anything is obvious to someone else. It's a good idea to use a standardized layout for reporting bugs. Here's the layout I like to use, complete with an imaginary bug:

Summary: A one-line description of the problem you experienced

Program.exe crashes when using "Save As" with long filenames

Description: Step-by-step directions to repeat the problem

  1. Launch program.exe
  2. Create a new file
  3. Type some text in the main window.
  4. From the File pulldown menu, choose Save As
  5. Enter a filename of at least 8 characters, and click OK
Actual Result: Exactly what happened when you followed the steps to repeat?

Program.exe crashed (include any debug information or interesting errors), and the file was not saved.

Expected Result: What did you expect would happen?

Program.exe should be able to use Save As feature with filenames longer than 8 characters.

Additional Information: Anything else that might help someone repeat the problem quickly

Next, verify that you've isolated all your variables:

Sometimes important details can be easy to overlook, but it makes all the difference in the world. Always try to err on the side of too much information, without overloading your bug report with useless data. Overworked, tired engineers won't always take the time to check all the possible combinations of operating system, and they shouldn't have to - it's not their core competency. There's a really good reason why QA exists in the first place: what makes someone good at QA isn't the same as what makes someone good at writing code. Some of the most brilliant coders I've worked with have been truly pathetic testers.

Another very important thing to consider is the tone of your bug reports. If you've never written code before, try it sometime. When you're done, hand it over to one of the programmers you work with. After someone gleefully crashes the project you've spent the last four hours coding, you will have a whole new understanding of the world of a programmer. It's especially common for new programmers to feel very defensive or even embarrassed, like QA is only there to point out everything they do wrong. Keep that in mind the next time you're reporting a crash bug. Everyone makes mistakes, it's a fact of software development. That's why you have a QA team in the first place. Your bug reports don't need to be full of schadenfreude, and no matter how witty you think you are, curb your humorous comments: the programmer who's going to be stuck at work for the rest of the night really won't enjoy the joke.

To sum it all up, here are the easy groundrules for reporting better bugs:

Good luck, and always remember to have fun!

~Lorna

Features Index | Home | Forums