How to handle a bug report effectively and efficiently

July 8th, 2007

In my previous entry on the subject of bugs i wrote that you’ll always have bugs, and that it’s a good thing. However, the former doesn’t automatically mean the later. You need to follow a few very simple steps to ensure that a bug report results in all those good things that i mentioned. So, let’s start:

  1. Don’t write a two-page instruction document on “the only true way” to report a bug. True, in some cases it will take a few e-mails back and forth to verify that it only happens under specific OS and specific VM. However, don’t create a 20-point flowchart that your user has to follow before daring to submit a bug report.
  2. Be open as to how the user can report a bug. Create as many channels as possible, including project forums, mailing lists and, last but most certainly not the least, private e-mail conversation. I can speak only for myself, but more than 50% of the bug reports that i get are sent to my personal e-mail account.
  3. Even if you don’t have the time to handle it right now, acknowledge the bug report as soon as you can. Most chances are, the user is still online, and you’ll be able to establish his trust and acknowledge his time (after all, he went to all the trouble downloading your library, using it and reporting the bug).
  4. Fix the bug as soon as you can, even before that sexy new feature that you want to add. A bug fixed on the same day will result in a very satisfied user. He will see that his time was not spent in vain, and that his report was handled in a quick and personal fashion. Wait a week and the user will have moved to another (competing) library.
  5. Related to the previous one – don’t pile up the bugs for the last few weeks before the next release. Mix bug fixing with adding new (sexy) stuff – this way you won’t get “turned off” during those pre-release weeks (assuming you’re doing it on your free time for the “fun” of it).
  6. In your “has been fixed” mail to the user, thank him for his time and ask to verify that the fix is working in the real application. If it is not working in the real application, send him a small test that you used to verify your fix and ask him to tweak it so it reproduces the original bug.
  7. Add the test scenario to your test applications. It can be either automated unit tests, or just another checkbox setting in your UI (some things can’t be automatically tested, especially on UIs).
  8. Always add comment in your code for a specific bugfix. One of the reasons is mentioned in this excellent article from “Joel on Software” – in a few months when you’ll want to refactor the code, you simply won’t remember why this specific line is there and will be tempted to just throw it away.
  9. If it’s not a programming bug, it’s a documentation bug. Update your FAQ, update your documentation, update your comments, update your Javadocs.
  10. Probably the most important one – put yourself in your users’ shoes. Ask yourself, what would you like to happen if you were the one reporting the bug. Would you be pleasantly surprised to get an instant confirmation mail? Wouldn’t it be great to have the bug fixed on the same day, or would you prefer the canned “will be fixed in the next release” reply? Wouldn’t it be great to see that your problem is acknowledged and addressed immediately?

Note that some of these points apply to the closed-source development as well. Even if you’re writing commercial or in-house software, it doesn’t mean that your users will be happy to wait (even if they have to wait, especially for in-house development).