How best to report a bug

As a software developer, bugs are a fact of life.  In fact, I welcome bugs, up to a point, because that tells me that someone is actually using my creation.  Too often when there are no bugs, especially early in the development cycle, that means that the end user is not actually using the product.  Then, inevitably, the bugs surface in production at the most inopportune time.

That said, there are good ways and less good ways of reporting a bug to the developer.  (This has much in common with reporting problems to your doctor or auto mechanic, as well.)  Here are some guidelines for reporting problems:

If there are multiple users, it is usually best to designate one person as the gatekeeper passing bug reports to the developer.  Often times, that gatekeeper will already know the answer and not need to bother the developer.

A statement that something does not work, with no way for me to reproduce or better understand the problem, does little more than tell me there is a problem.  That is necessary and helpful, but it does not allow me to solve the problem.

The best way to report issues is to send an e-mail (or log an entry in the bug tracking system) with the following:
1.       Clear & specific subject – “Grid data not saved” is a good, specific subject; “Problem with the program” is not a good subject.
2.       Preferably one problem per e-mail or bug report, to make it easier to track specific issues.
3.       Specific steps to reproduce the problem, if possible.

This last point is the most important. A statement such as “I was searching for a job/client/order and got an error message” does not allow me to see the problem.  But clear, reproducible steps, which consistently show the problem, allow me to attack the bug.

For example, here are the steps used to document a bug I was recently working on in a program used to analyze interviews:

Steps:
1.  Admin->Test->Restore
2.  Load canon003-30101-30202
3.  Demarcate mode
4.  Slide down to the end of the Interview pane.
5.  Click on separator between U16 & U17 (“Unclear S” & “I’m a little”) to remove it.
6.  Click on separator between U16 & the new U17 (“I’m a little horse now” & “<Laughter>”) to remove it.
7.  Click on space between “S.” & “I’m”.

The specifics of the progam being tested are not important here.  What is important is the level of detail.  As you can see, the steps provide the detail necessary to reproduce the problem.  Sometimes it is difficult to discern, let alone write down, the necessary steps. Sometimes the critical detail can be something as non-obvious as the size of the window on your screen or where you click – to the pixel – on your screen, for example.   If you can’t determine the steps to reproduce it, provide as much detail as possible – for example, does it happen with specific interviews or all interviews.  Does it happen on other machines, or only your machine.  Does it happen for other people following the same steps?

Finally, once you have a set of reproducible steps, try simplifying until you have the bare minimum set of steps which will still yield the problem.  Often times the initial set of steps includes lots of extraneous steps which obfuscate the real issue and make it harder to test. On the other hand, sometimes it takes many preceding steps to get to the point at which a problem manifests.  Just try to get to the bare minimum.

Once I can reproduce the problem, there is a very good chance I can solve it.  However, if I cannot reproduce it, or at least see it reproduced, there is almost no hope of fixing it.

Advertisements

About Dan Hurwitz

A consultant specializing in .NET.
This entry was posted in Software Development and tagged , . Bookmark the permalink.

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s