Defect reporting etiquette.

This should go without saying, however sometimes a little reminder is needed.  First of all, I presume that most of the readers here are actual developers of some form or another.  Maybe you're developing the next “killer app,” maintaining an internal accounting system, or just plinking out code in your spare time.  For most of you, people besides yourself use your application to make their life a little easier.  Basically, we all understand that the developer is the producer and the user is the consumer.  For one segment of the overall market, those consumers are other developers just like yourself.

Now that we've established that we all share at least one thing in common, even besides Delphi, is that we're all software developers.  I think we can certainly empathize with one another on one thing; defect or bug reports.  I certainly think that there is a certain etiquette one must follow to create a good, clear, and concise defect report.  This is especially true when reporting a defect to a fellow developer.  This developer may be on your team, or some unknown developer that creates some set of components on which you rely.

First of all, make sure you are able to reproduce the bug.  This is the most basic requirement in order to increase the likelyhood that the defect will be fixed.  The next item is try to narrow the case down as much as possible and eliminate as many variables as possible.  This will serve to keep the developer working to fix the problem focused on actually further understanding the issue.  Otherwise you risk sending that developer on a wild-goose-chase, which only wastes time and further delays the final fix, if it is even possible.  Sometimes a bug report may contain so many steps or variables that getting down to the real, core problem becomes an excercise in frustration and futility.

Finally, put yourself in that developer's position.  Remember, you're a developer, so please afford them the same courtesy you would want when someone reports a defect in your code.  What information would you want in the report?  What is a good threshold for numbers of steps?  It is rarely helpful to just dump you're entire project as an attachment in order to demonstrate the bug.  Most of all, just think about the perfect bug report from your perspective and try and come as close to that ideal as you are able.

“Oh sure“, some may be saying, “then I'll never report a bug because I just don't have the time to mess with all that crap!”  I'm sorry, but everyone has the same number of hours in the day.  You're time is just as valuable as everyone else's.  In fact by not reporting a defect, you're actually hurting your own productivity!  No software product is going to be 100% free of defects (mainly because many item's design and operation may be considered a “defect”), they can only be made better than before.  That can't happen if the developers of said software are unaware of the problems.  They also cannot be expected to use the product in the same ways that everyone else does.  That's why there are field or beta test programs.  These are essentially, volunteers that spend time using the product as they would normall use it.

“What if I just can't seem to faithfully reproduce a bug?”  In the ideal world, every defect is reproducable.  You should strive to narrow down the steps to as few as possible, and to eliminate as many other variables as possible.  However, in reality, it is never that simple.   Sometimes an encountered defect is simply not reproducable on command.  You may be asking, “So if I can't reproduce a defect, do I bother even reporting it?”  The simple answer is, “Yes!”  It's true that a single, lone non-reproducable report has little, if any chance of being fixed.  But that is the beauty of a community defect reporting tool!  By simply reporting the error message, and all other pertinant data you actually have, even if that is not enough information to actually reproduce the problem, you are adding to a growing database of data points.  What if you run into a defect and spent 30 minutes trying to narrow the steps or even just reproduce the problem all to no avail?  So you file a report anyway with all the data you currently have about the problem.  Then someone else sees that report and immediatly is able to spot some commonality between your report and 15 other reports that seem to have the same unreproducable issue.  Your defect report may have been the final bit of information in a long chain of data and finally forms a complete picture of the whole problem.

“Nobody can reproduce my defect report, but I have no trouble reproducing it! What do I do?”  This is another common scenario that sometimes discourages and frustrates people.  Don't fret!  We still want to have these kinds of reports.  Provide as much relevent information as possible, because just like the case in the previous paragraph, your defect may be the last key in a long standing quest to finally get to the bottom of a very complicated issue.  Ultimately, the developers and quality assurance team responsible for fixing and testing a certain defect must be able to reproduce the problem.  This makes sense, right?  I mean how else can you be sure you've actually fixed a defect if you cannot compare the behavior before and after making a change to the code?  You also need these steps and reproducability in order to plug this test case into a whole set of regression test suites.  How else can you make sure that a once a defect is fixed that it actually remains fixed and doesn't somehow re-occur in a later build?

“I don't have time to actually give you good steps and a good description of the problem.   It's not my job to be QA!  I'll just tell you that there is a problem in general terms and you guys can try and figure out the defect and fix it from there.”  Fair enough.  This is similar to the first scenario I presented, but there's some more things we need to cover.  Everyone's time is valuable and everyone's circumstances are different.  However, I do need to point out that if this is your normal modus operandi, there is something you need to be aware of.  Only you are the foremost authority on exactly how you work and what steps you took to encounter a defect.  It is very difficult for the QA staff to extrapolate enough information to form a decent defect report.  Also, unless clear and concise steps are given, how can we even be sure that we've actually found the defect you're reporting?  What if a completely different defect is found when trying to narrow the steps and that is attributed to the original reporter's report?  Sure, we've found and possibly fixed a defect, but how did that help the original reporter?  Their defect is still there even though we've now closed out the report as fixed.  That's not very helpful for all involved, is it?

I hope folks understand that by following a few simple rules and creating a defect report that you would like to get is actually you contributing to your own success.  In this one case I have to say that karma is the best way to describe this process.  By paying it forward and actually becoming a part of the solution, it will all eventually come back to you.  Even though you may think your contribution is tiny and insignificant, the fact of the matter is that your contribution when compounded with everyone else's can pay back in large dividends.  Quality Central is your friend!