As my current project moves into the testing phase, I am reminded of the importance of a well documented bug report. A bug represents a defect in a piece of hardware or software. The term "bug" most likely originated in the engineering community as a term used to describe a mechanical malfunction. Thomas Edison, in one of his letters, used the term to describe some problems with one of his inventions in 1878. So why do we need to spend time documenting a bug? The answer is easy if you think about it. An improperly documented defect is confusing and can often lead to an incorrect or incomplete bug fix which wastes valuable project time.
There are many different formats for bugs, but most systems share common attributes. Some of the more important attributes to developers are Description, Isolation, Steps to Reproduce and Severity. While there are other pieces of information that can be collected that are valuable, the information contained in the above fields is essential in creating an effective bug report.
Description is an explanation of the defective behavior. An effective description includes enough information for a developer to easily understand what the tester is seeing. When writing a bug description, verbose is better.
An example of a good Description:
"Download fails on Customer Report"
An example of a bad Description:
"Download doesn't work"
Isolation documents how the defect was identified as a bug. More succinctly, how do you know this is a bug? Isolation may include information about the requirement that is not being fulfilled or a description of similar functionality in another part of the system that works correctly. Isolation should not be subjective. If a bug's Isolation is subjective or missing, then there is no easy way to separate changes from bugs. In my experience, this information is most commonly omitted from bugs
An example of a good Isolation:
"Requirement 3.1.2 States that a user should be able to download the data from the Customer Report"
An example of a bad Isolation:
"Download doesn't work like CuteFTP"
Steps to Reproduce documents the process or conditions that are needed to duplicate the bug. The Steps to Reproduce should be clear to the developer. The tester should also include navigation information, any data, login ids or other settings needed by the developer to track down the bug. This is also a piece of information that is very often left off of a bug, especially with project teams whose members tend to work on only one or two areas of the application and are considered domain experts.
An example of good Steps to Reproduce:
- Login as cpalmer/bengals
- Click on the Reports Button
- Click on the Customer Report
- Select a date Range of 02/01/2000 to 03/10/2001
- Click on the Generate Report Button
- Click on the Download Button
- Error Occurs (Should ask user to save)
An example of bad Steps to Reproduce:
- Download the Report Data
- Error Page is displayed
Severity documents how significant the defect is to the normal usage of the application. Severity is generally a number between three and five and represents how much of a hindrance the bug is to the normal function of the application. The higher (although sometimes this could be reversed) the severity, the less able the user is to work around the bug. The lower the severity the easier it is to ignore the bug. Developer's can use the severity (usually along with a Project Manager assigned Priority) to prioritize the bugs that have been assigned to them. It also ensures that a major system defect is not missed due to an innocuous description
Some examples of Severity:
- Critical
- High
- Medium
- Low
- Cosmetic
Bugs are part of a developer's daily life. Whether or not your project has a formalized testing group or bug tracking system, the correct process for culling information about defects is vitally important to the predictability of your project. Too few developer's see bugs as what they really are, an opportunity to improve the end user's experience with your application. Keep that in mind and you can never go wrong.
Happy Coding!