The fundamentals of effective bug reporting

Updated: Nov 30, 2020

There is no dispute about the importance of writing an effective bug report, it's the main key to the success of any Bug life cycle (BLC). Effective bug reports should base on a few basic fundamentals that I will cover during this article.

Why effective bug reports are so important in the Bug life cycle? I know that you already know the answer, if not, just review this list:

  • Effective bug reports will increase communication among team members.

  • Effective bug reports will increase the chances that the bug gets fixed.

  • Effective bug reports will reduce the programmer investigation time.

  • Effective bug reports will validate that the bug contains all the necessary information that will help during the fixing and verification process

Bug reporting general guidelines

There are some basic guidelines that we must follow to make the bug report as efficient as possible:

  • Isolate the bug, make sure that you identify exactly what the problem is (Root Cause).

  • Keep it simple and do not exaggerate, you are not writing an article or crime report.

  • Make sure that the bug report describes one specific bug (One bug = one report).

  • Prior to opening the bug, validate that the bug does not already exist in the system.

  • Make sure that you use technical facts and not personal opinions.

  • Do not use any abusive language, remember that both you and the developer has the same goal.

The bug reporting Mandatory fields

Bug Title

Once the bug is opened, the title becomes the first thing that other engineers will see, as a result, the bug title should be meaningful, descriptive, and unique (usually built from 40-60 characters) in a way that will allow them to understand what the bug is without the need to read the full bug description.

Bug Description

The bug description is the area that should extend the information about the bug based on the bug title including many artifacts such as:

  • How this bug will affect the system.

  • Expected Vs Actual results.

  • The environment variables

  • Description of the bug.

  • Reproduction scenario.

There are a few simple guidelines that we can use to validate that the bug description is suitable for the exactable quality standards:

  • Make sure that the description reflects the true and entire picture.

  • Describe the bug without any exaggeration.

  • Don’t use inappropriate language.

  • Don’t add irrelevant information.

  • Use simple and clear language.

Reproduction scenario

A bug incident must include clear instructions on how to reproduce the problem so that others can reproduce it without the need to ask numerous questions.

A good incident report will include detailed information about the different phases that the programmer can follow to reproduce the bug, each step should include the relevant details and nothing more, remember that we do not need to write stories, just the MIN necessary information that will help others to reproduce the bug.

So how can you write a good reproduction scenario?

The reproduction flow must be clear.

  1. The reproduction flow must be informative.

  2. The reproduction flow must trigger the bug.

  3. The reproduction flow, should not include irrelevant steps.

  4. The reproduction flow must be tested prior to adding it.

  5. The reproduction flow must include a prerequisite list (Test Environment, Testing data...).

  6. Determine the reproduction availability

  7. Can you reproduce this bug?

  8. How much time does it take to reproduce this bug?

  9. Is this bug reproduced in the specific lab?

  10. Is this bug reproduced in different environments?

  11. Is this bug existing on older versions?

Details about the version and build

The bug report should include the name of the project, iteration, and the exact build number that the bug was found on.

Environment Details

In this section, we should add some background information about the test environment used when the bug was found, the minimum information should include information about the Device type, operating system, platform, and setup configuration.

Bug Severity

The severity of the bug will help to determine how severely the bug is in terms of damaging and affecting the system. For more information about bug "Severity" please read my previous article:

Bug priority

Determined by the team/project manager, and therefore I will exclude it from my review, but if you need more information you can use this link:

The Expected results

Remember, when you report a bug you describe an error or deviation from the system predefined requirements, in this section you need to describe the accurate way that the application should work.

Also, we must add the expected results based on documentation and NOT on your personal opinion, otherwise, the developer will follow your opinion and fix the bug against the actual requirements.

The Actual results

In this section, we will describe the actual results that we got based on the reproduction scenario/or on any case that we want to report although we don’t know the exact steps that cause it.