How to write a good bug report

Bug fixing is part of the job of every developer. Whether you are building a brand-spanking-new greenfield application or maintaining a 30-year-old ball of mud, you are going to have to fix bugs. 

Fixing bugs can be a challenge. Most of us have experienced the “take a day to reproduce it and two more days to figure out the problem, only to make a one-line change to fix it” situation.

A lot of factors go into the level of difficulty of fixing a bug, many of which are outside the control of the team. But one factor that makes a world of difference in a developer’s ability to fix a bug efficiently is the quality of the bug report.

We’ve all seen the bug report that comes to you in the form of the ever-helpful “This feature is totally broken!” When we ask, “What’s broken about it?”, we often receive the retort, “Nothing works!”

Not helpful. 

What is helpful? A well-written bug report. But those are all too elusive, right? Knowing how to write a good bug report is what separates a good developer or QA tester from the run-of-the-mill team member. A good bug report makes reproducing the problem easy. And, really, you can only fix bugs that you can reproduce.

There are five things that a good bug report should include, at least by my count.

Five ingredients of a good bug report

A clear and concise title

Succinct steps to reproduce the problem

Actual vs. expected behavior

Context and system details

Additional useful info

A clear and concise title

This might be the most underrated feature of a bug report. Most issue trackers will make the title prominent in whatever listings they provide in response to queries. Being able to tell what the bug is about—and precisely which bug it is—from the title is invaluable. Take a moment and make sure that your issue has a good title that makes clear to everyone what the basic problem is. Lots of people will be reading that title, and if it is concise and expressive, things will go better for that issue.

Succinct steps to reproduce the problem

This is the heart of the report, and easily the most important part. A developer will have a tough time fixing a bug that she can’t reproduce. You can’t expect her to fix it at all without the ability to see it happening. Thus, the steps required to cause the error are critical to resolving it.

And by steps, I don’t mean “Open the point of sale, sell something, pay with a credit card, and see the error.” That’s not good enough. You need to give every single action taken, down to the mouse clicks and keystrokes. The more detail in the steps, the better. If you are a QA person and the developer says, “There are too many detailed steps!”, pat yourself on the back and tell him to suck it up. You’ve done your job well.

Actual vs. expected behavior

Every bug occurs because one thing is supposed to happen but something else happens instead. Sometimes it is the wrong output. Sometimes it’s a crash. Whatever it is, a good bug report will define what should happen when the steps are followed and then very clearly detail what actually happens instead. You can’t fix incorrect behavior if you don’t know what the correct behavior is. Every bug report should make that very clear. 

Context and system details

No bug lives in a vacuum. Provide relevant context or system information that might be helpful. Include information on how the bug is impacting the customer, operating systems used, browser types, a query to run on the data to see the issue, etc. Include anything that might help explain the problem and its impact.

A good bug report will include pictures of the problem, particularly if it is a problem with the user interface.

Additional useful info

This is a bit harder to characterize, but I’d say the number one useful extra would be a video of the bug being reproduced. Seeing the bug in action is invaluable. Another useful aid might be a database that makes reproducing the issue easy. Many applications have settings in a database, the specifics of which are required to reproduce the bug. If the problem is a user interface issue, then a screenshot is obviously essential. 

Further thoughts

A few further considerations to note:

I don’t consider atrributes like Severity, Priority, and Customer Impact to be part of a quality report. They are important for triage and other such decisions and thus are useful to project managers, but developers don’t need to know about that. They just want to fix the bug.

Along those lines, though, a good, well-written bug report can make it easier to decide what to fix first.

If your bug reporting/finding tool includes a stack trace for the error, including that is very helpful.

Mentioning the build or version in which the bug first appeared is also valuable.

Writing a good bug report isn’t glamorous, and it can even be a bit tedious, but it is a valuable contribution to team success. A well-written bug report saves time, reduces frustration and wheel spinning, and makes the development process a touch smoother. 

So take the time. Bugs are inevitable, but confusion about what they do or don’t do and how to reproduce them is not.