Most programmers I’ve worked with are delighted to fix bugs in their code. Yes, really. It’s the social interaction which goes with it which is often the root of the problem. This is always a tricky subject because by definition something isn’t working right when you have to report a bug; you, the user, are frustrated because the software is not working as you expected and you might have very little control over getting the issue resolved.
I came across an old web page this week on how to report bugs. This is written from the programmer’s point of view, and I can say that it’s pretty close. In discussing it internally at my company around the “virtual water cooler,” I was reminded of the occasional travails experienced by our own Tech Support group in supporting our customers and getting us developers the info we need to fix those bugs.
The previously mentioned article talks about how to provide information to the developer to enable them to fully understand (and recreate) the issue. Recreating the issue is paramount so that once it goes away, we know we actually fixed the problem.
My own version of the summary from the article is this:
- The first aim of a bug report is to let the programmer see the failure with their own eyes. If you can’t be with them to make it fail in front of them, give them detailed step-by-step instructions so that they can make it fail for themselves. After writing down these instructions, go through them yourself to see if they actually produce the results you are describing. At last 50% of the time, the first set of step-by-step instructions are missing something.
- Don’t make assumptions, be crystal clear in your instructions, if a dialog needs to be dismissed, then note that; if you open something via a menu versus a shortcut key, mention that.
- Describe everything in detail. State what you saw, and also state what you expected to see.
- Write down any error messages *exactly* as they appear, spacing and capitalization and all. Hunting down an error message in the code is so much easier when you are looking for the correct string.
- When your computer does something unexpected, stop. If you start trying to fix the situation, write down each and every thing you do. Many issues are made harder to resolve because someone modified a setting and forgot to mention it.
- It’s okay to try to diagnose the problem, but in reporting what you think the error is (I think the catalog file is uninitialized when switching contexts), report *why* you think that, providing all the supporting evidence (pro and con) for your conclusion. You may be right, or you may be simply adding confusing information.
- Be ready to provide extra information if the programmer needs it. If they didn’t need it, they wouldn’t be asking for it. They aren’t being deliberately awkward. Have version numbers at your fingertips, because they will probably be needed.
- Be proud. You are engaged in a process to improve the world, or at least the small corner in which you live, or making your software work a little bit better.
It seems to be that there are some basic categories of bugs:
- Coding error in the software, an actual bug (2 + 2 comes up as 5 on your calculator)
- User error (I closed without saving, where’s my work?)
- Interaction with other software (this new Windows patch broke my website)
- Misuse of the product (I want to use a spreadsheet program as a word processor)
(The original article can be found here)
Martin O. Waldron
Program Manager, SW Development