Best Practices for Reporting Bugs

As a programmer, one of the things that I enjoy most is solving problems by creating new solutions. While I enjoy solving complex larger issues, I also love fixing an existing problem in the form of a bug. Bugs usually have a distinct problem that needs to be solved. When I am working on a bug fix, my mind usually cannot rest until I have come up with a sufficient solution. Once I have come up with a solution for a bug, there is a personal satisfaction that comes knowing the bug is resolved. One of the most difficult things in fixing bugs is insuring that I have all the details to reproduce a particular bug. Being able to reproduce an issue is important in bug fixing. This provides a developer or programmer a test case to assist with debugging and testing the final solution. As a developer on many projects, I spend a considerable amount of time communicating with bug reports to insure I have all the necessary information to reproduce the bug. Often times, a bug report contains some information to get started in working on a solution, but not all of the information needed. The less time I spend deciphering the issue means I will spend less time fixing the bug and providing a solution. This post will highlight some best practices and tips for filing a bug report.

Anatomy of a bug report

A bug report usually contains a set of fields for tracking specific information, a description field for describing the task, the ability to move the bug through different states, and provide additional comments as a solution is being worked out. At a minimum, most bug tracking application include the following fields:

• Priority
• Status
• Assigned to
• Description
• Reporter

Along with tracking these fields some basics are usually captured as well such as date and time. These fields insure all the necessary information can be referenced when addressing an issue. The status field is important because it is used to communicate the stage or state that a bug is in. A bug typically goes through the following stages:

• Open
• Assigned
• Fixed
• Verified
• Closed

Guidelines for reporting bugs

The most important part of a bug report is to provide the steps necessary to reproduce the issue. If you include all the steps and the details associated with reproducing the bug, then all of the important information should be captured. Screenshots and URL's are also important so that the developer can quickly locate and try to reproduce the problem. When writing a bug report, try to put yourself in the developers shoes and ask "What would I want to know to be able to investigate and fix this problem?". Here are some key items to think about and include with your bug report:

• Title: The title should be concise, clear, and informative
• Do not use vague language such as "crashed" or "failed" instead include an error message, or exactly what happened
• Separate issues as best you can into individual bug reports. It is often tempting to clump several bugs into one bug report. This can be confusing as they all will have different test cases and some parts of the bug may get resolved before others.
• Include details steps on how to reproduce the bug including the URL. If you are logged into a system include the username and/or role that you are logged in as.
• Include browser version and operating system
• Be specific and verbose in documenting your bug entry. The more detail that is included in the report will expedite the process of solving the bug.
• Annotated screen shots are extremely helpful. If possible, include the location bar that shows the URL in the screenshot

Questions to ask?

There are a number of questions you should answer in your bug report.

• Can you reproduce this bug?
• Can you reproduce this bug in another environment or on another machine?
• Does the bug occur in only one browser or in multiple browsers?
• Has this ever worked before?
• Does the bug report contain enough information for someone to reproduce the bug?

Summary

Writing a detailed bug report will expedite the bug solving process. Having a clear and concise title will insure that bug reviewers can have an idea at a glance on the issue. Separating out issues into individual bug reports will allow each issue to maintain its own status and be resolved independently of each issue. Once you have written your bug report, you should review it one last time to insure that you have included all the necessary information. It may take a little longer to file the bug report initially, but I guarantee you it will reduce the amount of back and forth communication required to solve the bug.