Anyone can spot a bug, but how many of us know how to report it properly? Every person who has written software for public use has probably received some bug reports really hard to understand. These are the reports that don’t say nothing, like “it doesn’t work”, give the wrong information or no information at all. In order to make it work the best way it is importat to know how to write useful bug reports, where the errors are stated clearly.
Why are bug reports important?
The role of bug reports is to help the programmer to see how the software is failing. It can be done in person or by giving them a virtual report. This is why is so important to state as many information as possible in every bug report, like “I clicked this button when this happened”. On the other side, it’s really important to state the speculations, like “I think the problem might be this”. Useful bug reports work more on facts and less on speculations.
At the end, if you are reporting a bug, is because you want it to be fixed, right? So why not making an useful bug report that gives all the information in a clear and simple why? This way the bugs will get fixed faster and you’ll not be angry with them anymore. Also, if a software is free, remember that this means that the author is providing it thanks to their kindness, so the way you approach your feedback can influence their willingness to develop the software further or not.
Remember, the better your bug report is, the quicker the problem ca be solved. It has to enable the engineer to understand WHY there is a problem, but also give them the information to be able to reproduce that bug on their own system and solve it.
How does a good bug report look like?
Writing useful bug reports is a skill that anyone can develop. As Cem Kaner states, “the point of writing problem report (bug report) is to get bugs fixed”. It is important to be aware of what a useful bug report means, one that a programmer will not reject because of being irreproducible.
There are some characteristics every great bug report should have:
- Be reproducible – Make sure that the bug can be reproduced and that you give all the necessary steps to do so. Do not assume that the programmer knows already, otherwise the bug will never get fixed.
- Be specific and informative – Bug reports are not essays contests, it is important to be specific and to the point. Use a few words to summarize the problem in an effective way, like “I pressed Alt-L when this happened”. Words matter a lot, so take care which ones you use. Also, avoid to combine different problems, even if they look similar.
- Include a clear specified bug number – it is important to always assign an unique number to each bug report, in order to identify it easier. Automated bug-reporting tool will generate this number automatically.
- Be verbose – Anyhow, it’s better to give more information rather than less. If you say too much, the programmer might ignore a part of it. But if you say too little, the programmer might not have all the necessary information in order to solve the problem.
What is the structure of a useful BUG report?
This is the basic structure of an useful bug report, with the most important things that you should include.
- [Feature Name] Title
- A good summary
- Steps to reproduce
- Expected Result
- Actual Result
- Visual Proof (screenshots, videos, text)
- Type of severity:
Blocker: No further testing work can be done.
Critical: Application crash, Loss of data.
Major: Major loss of function.
Minor: Minor loss of function.
Trivial: Some UI enhancements.
Enhancement: Request for new feature or some enhancement in existing one.
Tips and tricks for useful bug reports
Anyhow, more than writing the information, it’s important how you write the bug reports. These are some tips and tricks that will help you to have useful bug reports.
Write a great bug summary – Bug summaries are used as references when you search a bug in the bug inventory. Having a great bug summary will help the developer to understand faster and easier the problem
Report the problem immediately – Do not wait too long if you found any kind of problem. If you want to solve it fast, report it faster.
Report the bug 3 times before writing the bug report – This will assure one of the most important characteristics of bug reporting, being reproducible.
Additional resources – You can include a link (if it’s relevant) or even better, a screen shot.
Give a couple of examples – The examples should include the steps that you take (Go to www.example.com/login, enter username in the login field, put wrong password); the outcome you expect (“to show error message “incorrect name or password”); the outcome you actually have (login fails with “incorrect username” message) and, last but not least, the problem. In this specific case it was misleading giving an error message about the username, when the problem was clearly the password.
Be careful with pronouns – Words like “it” can be misleading if you don’t specify exactly what they mean. An example of this: “I started BlueApp* and a warning window appeared. I tried to close it and it crashed”. Which one of the two crashed? The App or the window that appeared? This is why it’s important to specify all the time to what you refer about.
Read what you wrote – We might tend to write immediately after something doesn’t work, but reading what we write will help in assuring that the information is relevant and clear. Otherwise it can look like you are just complaining.
Everyone can write a bug report.
The challenge is to write an effective one, right? At the end, the useful bug reports are the one that will help the developers to solve the problems as quick as possible. Remember, the purpose of bug reports is to fix the bugs. More than what you write in the report, it matters how you write it.
We hope you enjoyed this article. If you have any questions or you just want to share with us something, we are one message away! Get in touch with us here!