The Art Of Reporting Bugs
My initial intention was doing a write-up on debugging tips, then it dawned on me that even before debugging an issue, there needs to be an emphasis on how the bug is being reported. So in this post, I want to share my takes and thoughts in reporting a bug. A small precursor, I work in a semiconductor company and so my bugs are Hardware/ Software or maybe a combination of both. Thus it becomes that much complex for the engineer or the engineering team to fix the bug reported by customers. These tips should be useful for reporting any kind of bug (i.e. Hardware or Software)
Being in the Applications team more often than not we are the ones that escalate the customer bugs to Engineering. What I learned is that the effort put into reporting a bug is much important as working on the solution of the bug. Since the clearer in reporting the faster, the bug will be fixed.
So here we go…
Tip 1: Engineer is not a Bad Person who Planted the bug
Seriously, The engineering department/engineer did not plant the bug intentionally, so when you come across a bug and are in a situation to report it, think that as a challenge that is facing the engineer “and” yourself. Both of you are a team in resolving the bug. Just this thought process will make you more co-operative. Try not to think that solving the bug is 100% burden on the engineer. As a reporter of the bug, you too have a good amount of stake in solving the bug.
Tip 2: Give Detailed Steps
This one is really critical. Anybody who reports the bug has to describe the steps to reproduce the bug and all of them will. The difference lies in the quality of the steps. Let's take an example of two descriptions of the same bug and you decide which one is better (P.S: for now ignore the technicalities )
Description 1:
When there are three “Type A” Devices in a network and one “Type B” Device. When “Type B” Device tries to join the network (“Type B” Device being Network coordinator), the other devices do not allow the “Type B” Device to join the network and the whole network crashes.
Description 2:
- Connect three “Type A” Devices and 1 “Type B” Device in a Network
- Power Up all The Devices
- Issue “Command 1” in “Type B” Device to Make it as Network Coordinator
- Type “Command 2” in “Type B” Device’s Console to get the number of devices in the Network and observe output as 4.
- Power Cycle “Type B” Device
- Type “Command 2” in “Type B” Device’s Console for the number of devices in the Network and observe that the output is 0.
- The expected output in “Step 6” is 4
Obviously Description 2 is clear. Here are the reasons...
- Description 2 actually “has” numbers for each step. Numbering the steps is almost always clearer than non-numbered steps.
- Description 1 just says that the problem is happening, it does not say how to reproduce the problem. Whereas, Description 2 clearly describes how to reproduce the problem.
- Description 2 has all the three critical parts needed in describing a bug...
a. Setting the stage for the bug to happen, Steps 1–5
b. The actual behavior of the system, Step 6
c. Expected behavior, Step 7
more often than not we receive the bug descriptions as in Description 1. Of course, the flip side is too many steps. To me, this is also a kind of deterrent, try to keep the steps to the optimum. The worse is, The bug reporter sends a very lengthy description in the form of Description 1 and gets frustrated that the software engineer does not follow his procedure :).
Tip 3: Report Hardware/Software Version
Almost always try to mention the version number of the software, hardware or both. In embedded systems, it's also a good practice that Software Engineering provides a facility to extract the version number during run time. Some kind of console application which prints the version of the software in focus (something like the $uname -r command in Linux)
Tip 4: Use Diagrams, Pictures, and Videos
When you are describing the bug use Diagrams generously (as the saying goes picture is worth a thousand words) and corollary to that is taking pictures. Nowadays its easier than ever to take pictures and videos. I am pretty sure most engineers will have the thing called a “Smart Phone” and there is a 100% chance that it has a still/video camera built into it.
Taking pictures may be more useful if you are reporting a bug in a system that has both hardware/software involved (hardware Setup, connection details, etc..).
Tip 5: One bug, one report
I have seen this happening. The bug reporter starts off with the main issue and says “Oh BTW we also see this other issue” or during an active debugging phase of the reported bug, the bug reporter finds another issue and describes it in the same report (in the comments section). There’s nothing confusing than this. If you are not sure if the bug is the same or different, create a new report anyway. If it was indeed the same bug then it can always be marked as duplicate.
The Bug Database should not be used as a dumping ground. Treat it like a database of knowledge. Keep in mind that the current “active bug” is a future reference to learn (We all learn from mistakes, don’t we)
Tip 6: Heading be relevant to a reported bug
This happens more often if the medium of bug reporting is email. The Heading of the Bug should be relevant to the actual bug description and should remain relevant during the whole life cycle of the bug. This may sound trivial, trust me, it gets confusing if you have 10 bugs to solve in 20 email threads :)
Tip 7: Document the closure of the bug
A proper closure statement is needed. This can be either a brief or detailed description of the root cause and the fix that was done to solve the issue.
There it is. All the above tips are derived from my experience as both a bug reporter and a bug solver. Do you have any more tips? Please feel free to share it in the comments section.
Happy bugging to debug :)
