Bugs, bugs, bugs! Talking about software development is impossible without also talking about bugs. At first, the term “bug” may seem like strange slang for “defect.” Are there creepy-crawlies running about our code and computers? Not usually, sometimes yes! In 1947, Grace Hopper found a dead moth stuck in a relay in Harvard’s Mark II computer, and her “bug” report (pictured above) joked about finding a real bug behind a computer defect. Even though inventors like Thomas Edison had used the term “bug” to describe technological glitches for years beforehand, Grace Hopper’s bug cemented the terminology for computers and software.

Bugs happen. Why? Nobody is perfect, and therefore, no software is perfect. Building software of high quality requires good designs to resist bugs, good implementations to avoid bugs, and good feedback to report bugs when they inevitably appear. This article covers best practices for writing good bug reports when they do happen.

What is a bug “report”?

A “bug” is a defect, plain and simple. The term refers specifically to an issue in the software. However, a bug report (or ticket) is a written record detailing the defect. Bug reports are typically written in a project management tool like Jira. The bug and its report are two separate entities. Certainly, undetected bugs can exist in a software product without having associated reports.

When should a bug report be written?

A bug report should be written whenever a new problem that appears to be a defect is discovered. Problems can be discovered during testing activities like automated test runs or exploratory manual testing. They can also be discovered while developing new features. In the worst case, customers will find problems and submit complaints!

However, notice how I used the term “problem” and not “defect.” All problems need solutions, but not all problems are truly defects. Sometimes, the user who reported the problem doesn’t know how a feature should work. Other times, the environment in which the problem occurred is improperly configured. The team member who first discovered the problem or received the customer complaint should initially do a light investigation to make sure the problem looks like a genuine software defect. Initial investigation should be done expediently while context is fresh.

If the problem appears to be a real defect and not a misunderstanding or misconfiguration, then the investigator should search existing bug reports for the same issue. Someone else on the team might have recently discovered the same issue or a similar issue. Bugs also can reappear even after being “fixed.” Adding information to existing reports is typically a better practice than creating duplicative reports.

What if the problem is unclear? Whenever I’m not sure if a problem is a bug or another type of issue, I ask others on my team for their thoughts. I try to ask questions like, “Does this look right? What could cause this behavior? Did I do something incorrectly?” Blindly opening bug reports for every problem is akin to “the boy who cried wolf” – it can desensitize a team to warnings of real, important bugs. Doing just a bit of investigation shows good intentions and, in many cases, spares the team extra work later. Nevertheless, when in doubt, creating a report is better than not creating a report. A little churn from false positives is better than risking real problems.

Why should bug reports be written?

Whenever a real bug is discovered, a team should write a report for it. Simply talking about the bug might seem like an easier, faster approach, especially for smaller teams, but the act of writing a report for the bug is important for the integrity of the software development process. A written record is an artifact that requires resolution:

• A report provides a feedback loop to developers.
• A report contains all bug information in a single source.
• A report can be tracked in a project management tool.
• A report can be sized and prioritized with development work.
• A report records work history for the bug.

Bug reports help make bug fixes part of the development process. They bring attention to bugs, and they cannot be ignored or overlooked easily.

What goes into a bug report?

Regardless of tool or team process, good bug reports contain the following information:

• Problem Summary
  • A brief, one-line description of the defect
  • Clearly states what it defective
  • Should be used as the title of the report
• Report Identifier
  • A unique identifier for the bug report
  • Typically generated automatically by the management tool (like Jira)
• Full Description
  • A longer description of the problem
  • Explain any relevant information
  • Use clear, plain language
• Steps to Reproduce
  • A clear procedure for manually reproducing the failure
  • Could be steps from a failing test case
  • Include actual vs. expected results
• Occurrences
  • Cases when the defect does and does not appear
  • Share product version, code branch, environment name, system configuration, etc.
  • Does the defect appear consistently or intermittently?
• Artifacts
  • Attach logs, screenshots, files, links, etc.
• Impact
  • How does the defect affect the customer?
  • Does the defect block any development work?
  • What test cases will fail due to this defect?
• Root Cause Analysis
  • If known, explain why the defect happened
  • If unknown, offer possible reasons for the defect
  • Warning: clearly denote proof vs. speculation!
• Triage
  • Assign an owner if possible
  • Assign a severity or priority based on guidelines and common sense
  • Assign a deadline if applicable
  • Assign any other information the team needs

I use this list as a template whenever I write bug reports. For example, in a Jira bug ticket, I’ll make each item a heading in the ticket’s “Description” field. Sometimes, I might skip sections if I don’t have the information. However, I typically don’t open a bug report until I have most of this information for the defect.

How should bug reports be handled?

One word: professionally. Handle bug reports professionally. What does that mean?

Provide as much information as possible in bug reports. Bug reports are a form of communication and record. Saying little more than, “It dun broke,” doesn’t help anyone fix the problem. Provide useful, accurate information so that others who didn’t discover the bug have enough context to help.

Triage bugs expediently. When you uncover a problem, investigate it. When you need a second opinion, ask for it. When someone sends a bug report to you or your team, triage it, fix it, and reply to the person who reported it. Don’t ignore problems, and don’t let them fester.

Treat bug reports as unfolding stories. Bugs are usually unexpected, tricky surprises. The information in a bug report can be incomplete or even incorrect because it represents best-guess theories about the defect. The report artifact should be treated as a living document. Information can be added or updated as work proceeds. Team members should be gracious to each other regarding available information.

Do not shame or be shamed. Bugs happen. Even the best developers make mistakes. A mature, healthy team should faithfully report bugs, quickly resolve them, and take steps to avoid similar problems in the future. Developers should not stigmatize bugs or try to censor bug counts. Testers should not brag about the number of bugs they find. Language used in bug reports should focus on software, not people. Gossiping and public shaming over bugs should not happen. Any shame associated with bugs can drive a team to do bad practices. Any recurring issues should be addressed with individuals directly or with the help of management.

Good bug reports matter

Writing bug reports well is vital for team collaboration. Organized, accurate information can save hours of time wasted on fruitless attempts to reproduce issues or attempt fixes. Give these practices a try the next time you discover a bug!