Do’s and don’ts of bug reporting

Bug reporting is meant to help developers with debugging. However, a bug report must have certain characteristics to be considered helpful.

For example, developers are unlikely to be thrilled if the report offers no screenshots or environment specifications (browser, network, etc.).

On the other hand, they’d probably love a bug report with a clear structure.

In other words, there are good and bad things to do while debugging. If you’re unsure what they are, don’t worry—you’re in the right place.

This article will walk you through all the do’s and don’ts of bug reporting.

Bug reporting do’s

A bug report serves as a starting point and a guiding light to help resolve the error in the code as soon as possible.

Or, in the words of acclaimed software developer Cem Kaner:

When writing a bug report, this maxim should always be in the back of your employee’s mind.

They should continuously ask themselves: is this helpful information? Will this help the developer solve the bug?

So, in order to create a useful bug report, we recommend embracing the following practices.

Making sure the bug is reproducible

Developers will debug more quickly if they can see the error themselves.

The bug report might contain a page-long description with exact environment specifications, but there’s nothing more effective than having the bug right in front of you.

As such, it’s crucial to ensure the bug is reproducible. In other words, every report should contain the steps to make the bug reoccur.

This is essential, as the pathway to bugs isn’t always obvious.

For example, some bugs will only occur on a specific operating system (e.g., Android), others only in dark mode, etc. The combinations are endless.

The below cartoon does a good job depicting the intricacies of reproducing a bug:

Although exaggerated for comedic effect, the image expresses an underlying truth. If even one variable is incorrect, there’s a high chance the developers won’t be able to replicate the bug.

As a result, the steps to reproduce the bug should be clear, comprehensive, and concise. Ideally, the developer will be able to recreate the bug effortlessly.

Here’s an example of well-written steps to reproduce:

The text first specifies the environment and then offers straightforward yet detailed directions on replicating the error.

With these instructions, the developer will have no trouble reproducing the bug in order to make a report that will lead to it being fixed.

Structuring the bug report

A bug report should be clear and straightforward—there should be no ambiguities regarding the bug’s specifications.

An easy method to achieve this is adhering to a predefined structure. By consistently following a standard outline, your developers will digest the reports’ content much faster.

There are numbers to prove it:

With a standard template, your developers will be able to easily navigate the document.

If you’re unsure about how to create a structure, we suggest starting with the information in the visual below, as these datasets are crucial.

The first thing on the report should be the bug ID or title, ideally a brief description of the error.

After that comes severity and priority, which quantifies how serious an issue is.

Following that is a more detailed description—essentially a more elaborate version of the title.

You should also specify the environment (e.g., application version, browser, network connectivity, etc.).

The steps to reproduce are next. They should be kept short and sweet yet descriptive.

Another valuable component is the expected result vs. the actual result, which compares how the software works and how it should be working.

Finally, attach any relevant files, such as screenshots and screen recordings.

Being descriptive in the bug report

Although having a structured document is hugely beneficial, it’s still only half of what constitutes a great bug report.

To facilitate debugging even more, you should ensure the document is detailed and crystal-clear.

With a descriptive bug report, developers will be more likely to understand all the error’s details and, therefore, quickly repair the problem.

They won’t waste time tracking down information or making sense of the report.

The cartoon below depicts what a descriptive bug report looks like in a humorous way:

Despite the comedic parallel with a real-life insect, the image provides an excellent overview of a bug report’s essentials.

As you can see, the report should include the time and date of the bug’s discovery, provide details on how to find it, highlight how dangerous it is, and explain its environment.

Here’s an example of a well-composed bug report:

The report’s description is written in simple yet descriptive language, making it easy to understand the problem.

Furthermore, countless other details provide a developer with all the necessary technical specifications concerning the architecture, installation media, and even the exact date and time.

With such a descriptive report, the developer should have no problem resolving the issue quickly.

Using the right bug reporting tools

It can be overwhelming to keep track of all the different aspects of bug reporting—mainly because it’s essential that nothing is accidentally omitted.

Because the process is so complex, it’s not a bad idea to invest in bug reporting tools.

With such resources, your team can streamline this fairly lengthy, manual process into a quick, automated procedure.

For example, with Shake, all you need to do is shake your mobile device, and a bug report is instantaneously generated. The document is then immediately sent to the developers.

Here’s a sample bug report:

The report is submitted in two seconds and contains everything the developers need: screenshots, screen recordings, environment details, logs, steps to reproduce the error, app version, etc.

If you have a web application on your hands, Marker is a superb bug reporting solution. The tool allows users to report bugs visually and attach annotations.

However, it will also automatically include all relevant technical information.

Here’s the tool in action:

With all these details added, developers will have a much easier time correcting the error.

This is the advantage bug reporting software brings—it streamlines manual processes into high-yielding automation.

Bug reporting don’ts

Just as there are certain recommended habits in bug report writing, there are also several pitfalls to avoid.

Imagine if your developers received a bug report missing essential information (e.g., environment details) or one that was so poorly structured that it takes several minutes to understand the text.

They’d likely put that report at the end of their to-do list.

For example, look at this bug report:

The interface is bland and lifeless, and several fields are missing crucial data. No one would want to be assigned this bug report.

To avoid such unhelpful documents, it’s a good idea to steer clear of the following practices.

Waiting too long before creating a report

If you wait too long to report the bug, your team members might scramble to solve the issue before a deadline, and consequently, their solution might not be the most elegant.

On the other hand, when an error is reported immediately, there’s much more time to fix it, and the developers can construct a more effective resolution.

Apple has also highlighted the benefits of reporting errors early, as shown below:

Reporting bugs early on is crucial, as these reports can contain time-sensitive information. The longer you wait to solve a problem, the more damaging it can be to your software.

And that’s not the end of it. Long-living bugs also harm your project in another aspect— monetarily.

It’s much easier, and therefore more cost-efficient, to correct an error during early software building.

If your developers are debugging in late development or before release, your business is effectively losing money.

The graph below illustrates this concept well:

If a bug is corrected in conception or design, the cost of fixing it is significantly lower than later on. This alone should be enough incentive to avoid waiting too long before writing a bug report.

Reporting multiple bugs in a single report

Bugs are best captured one at a time. A codebase is a labyrinthine environment, full of dependencies and layers, and therefore seldom easily navigable.

To make matters worse, somewhere in all those code lines are bugs—errors to be corrected.

Given these intricacies, it’s best to avoid reporting multiple bugs in a single report. Solving one error is challenging enough.

If the document contains several issues, it’s near impossible to juggle all the separate bugs.

For example, consider the following report:

The application crashes after clicking on SAVE. If I click on EDIT, nothing happens, the application stays on the same page. Also, I cannot see a DELETE option.

This bug report would only frustrate your developers.

Although these various buttons are likely on the same screen, the bugs themselves might not be connected, making solving all three in one report nonsensical.

Each is its own separate issue and therefore deserves a separate report.

Submitting duplicate bug reports

The chief benefit of bug reports is that they make debugging efficient, as they contain all the details needed to start fixing the error.

However, if duplicate reports are submitted, all this creates is clutter, and debugging efficiency drops instantly.

A bug may be solved, but because a duplicate report is still open, developers will infer the bug is active.

They’ll start solving an already resolved issue, which can cause significant problems, as the following quote summarizes:

Firstly, the developer will be spending time on a redundant task when they could be focusing on more critical issues.

Secondly, they might make unnecessary changes to the codebase—some of which can cause more harm than good and possibly impair its recently-solved functionality.

This can easily impede development.

These dangers become especially apparent when considering the frequency of duplicate reports:

With duplicates occurring so often, it’s essential to check the list of known issues to see if a bug has already been pointed out.

To be extra sure, your employees can also always ask their team members, as they might recall if a certain bug has been reported.

You’ll want your developers to be as thorough as possible, as submitting duplicate bug reports severely diminishes productivity.

Leaving feedback in bug reports

A bug report is not the same thing as a suggestion. If it was never explicitly stated that the homepage images should be a carousel, then the fact that those images are static doesn’t constitute a software error.

Although some think carousel images are a better design choice, the fact that this feature was not implemented is not synonymous with a development bug.

Therefore, your employees must refrain from expressing their personal preferences in bug reports. A bug report should be limited to issues that require fixing and nothing else.

Yegor Bugayenko also echoes this sentiment, stating:

Although a tad harsh, the reasoning is sound. Developers who take on bug reports are there to solve problems, not make design changes.

By expressing feedback in bug reports, the document loses its purpose and clutters a developer’s workflow.

As strange as it may sound, even positive, appreciative feedback isn’t desirable in a bug report. This phenomenon was also discussed on Reddit:

This developer maintains that the information in a bug report should be relevant. Words of praise, however flattering, are nonetheless irrelevant to the issue at hand—solving an error.

A bug report should be technical and formal, fixated on resolving an issue. Feedback, even of the positive kind, does nothing but detract from this.

Conclusion

Bug reporting is a precise, formal process. The document serves as a debugging starting-off point—it gathers all relevant information so developers don’t spend time looking for it.

A bug report should be structured and descriptive, including essentials such as steps to reproduce. It’s also a good idea to invest in a bug reporting tool.

Avoid reporting multiple bugs in a single report or submitting duplicate reports.

Furthermore, refrain from leaving feedback in the report, and don’t wait too long before submitting the document.

Keep these guidelines in mind, and your team will soon be composing flawless bug reports.