9 Best Practices for Software Bug Reporting

Most developers have a love/hate relationship with software bug reporting. They love bug reports because they’re a crucial vector for getting feedback from software testers and users about ways to improve an app. But they hate them because, well, responding to bug reports is not high on the list of most developers’ ways to have a good time.

That’s especially true when they’re dealing with bug reports that are redundant, poorly written, hard to follow or otherwise problematic. Those reports tend to receive the least priority, and they may aggravate developers so much that they choose not to respond to whatever issue or issues the reports contain.
That’s why, if you want your bug report to receive the attention it deserves, it’s critical to prepare it well. Following are nine best practices for software bug reporting, whether you’re an engineer reporting bugs to your own team, or an external end user filing a bug report about software you use.

1. Clearly and specifically identify the issue.

First and foremost, your software bug reporting should clearly and specifically identify whatever issue you are seeking to communicate to developers.

You might think this would go without saying. But it’s easy to fall into the trap of writing a bug report that isn’t specific enough about what is actually wrong because you describe the issue in terms that are too generic.

For example, a report that says there is a “degradation in performance” under certain conditions isn’t very specific. It would be better to say exactly how performance degrades: Does the interface stop responding? Is there a noticeable delay in the application when handling requests that involve the network? Does the application consume more system resources?

Another way of thinking about how to identify the issue clearly is to write what you expected to happen, then describe what actually happened. “I expected the interface to keep responding, but it became unresponsive and grayed out after I clicked the green Start button” clearly identifies what is wrong.

2. Stick to one issue per bug report.

Another basic best practice for software bug reporting is to stick to one issue per report. If you’re experiencing multiple problems with an application--like a slow initial launch and a laggy interface once the application is running--report each issue separately.

This may seem intuitive enough. But where folks often go wrong is when they assume that the different issues they are experiencing are related and should therefore be reported as a single bug.

In reality, two seemingly similar problems may or may not be connected. Whether they are is a determination for developers to make as they research and fix the issues. If developers later decide that two issues are related, they can merge bug reports accordingly. Leave this up to them to figure out.

3. Don’t suggest a bug cause or fix.

When you file a bug report, you may have your suspicions about what you think the cause of the problem is. Maybe you suspect it’s related to a certain software library or that it was caused by a specific update, for instance.

You may think that offering such suggestions to developers within the bug report will help them fix the issue faster. But the fact is that it’s usually better to let developers figure out what’s going on themselves, without pushing them in certain directions. This allows for a more objective response, while also avoiding the need for developers to note in the bug report why your suggested fix is not the right fix.

The exception is if you have already explored the issue yourself and drawn conclusive results about the cause. If you’ve tested different versions of the application under the same exact conditions and have determined that the problem occurs only with one version, for example, that’s worth noting. But simply saying that the problem began occurring following a recent application update, without conclusive evidence to show that the update is related to the problem, is not very helpful.

4. Make sure the bug keeps occuring.

Sometimes, what you think is a real bug in an application turns out to be a temporary glitch that was caused by a rare and temporary condition in your environment. These issues are usually difficult to duplicate (which makes them hard to research and fix) and are not common enough to merit serious remediation efforts by developers.

A rule of thumb to avoid wasting developers’ time on reports about rare, one-off issues is to make sure the problem you intend to report occurs at least three times before you file a report. Otherwise, if you can’t duplicate it consistently on your own system, it’s unlikely developers will be able to trigger the bug in a way that allows them to understand and address it.

5. Avoid technical jargon.

Software bug reporting may seem like a place where technical jargon will be welcome. In fact, you may even think that developers expect you to use technical language, because that’s how they’re accustomed to communicating with each other.

However, unless you’re reporting a bug for your own team and are certain which technical terms they will and will not recognize, it’s best to stick to plain English. Don’t say, “The app forked a new process, which caused the UI to hang until the app seg-faulted and the kernel panicked.” Say, “After a new instance of XYZ process started, the interface stopped responding, then the application crashed, and finally the entire operating system became unresponsive until I rebooted the computer.”

6. Keep the bug report brief, and stick to the facts.

You may think that the more information you share in the process of software bug reporting, the easier it will be for developers to respond. In reality, developers who have dozens or even hundreds of reports to sort through want each one to be short, sweet and to the point.

Include relevant data, like information about application and operating system versions. But avoid extraneous narratives, like, “I first installed this app two weeks ago, and up until yesterday it worked great. Then, today, after I opened an email, it started acting weird.”

7. Include command-line output, if possible.

Some applications can run both on the command line or using graphical interfaces. In general, you’ll get much more debugging data on the CLI than you will from a GUI.

So, if your app has a CLI version, be sure to try running that version to see if you experience the same problem as you do when using a GUI. If not, then you know the problem is limited to the GUI. If so, you’ll likely get more information from the CLI that you can share in your bug report.

8. Don’t conflate feature requests with bug reports.

Sometimes, users who file bug reports aren’t actually reporting a bug. They’re requesting a new feature or application enhancement.

Some developers use the same tracking systems for bugs and feature requests, but they treat different types of records for each one, and users have to know what they’re requesting when they file the initial report or request. Others use entirely different systems for feature requests, and some may not have a formal feature-request system at all; they may instead expect you to start a discussion on their mailing list.

Whatever the case, be sure that, if you want to share your ideas for a new feature with developers, you use the right avenue and avoid filing a bug report for something that is not a bug.

9. Remain available after filing.

The best-written bug report is of little use if the person who wrote it disappears after filing. It’s very common for developers to request additional information from the person who reported the bug, so remaining available after you have filed the report is just as important as filing a good report in the first place.

Conclusion

When it comes to software bug reporting, following best practices for writing clear, concise and focused bug reports will help the developers of your software love your bug reports that much more. In turn, you’ll enjoy faster resolution of whichever issues you face in using the software, not to mention a better reputation among developers.