How You Talk Yourself Out Of Reporting A Bug

Wednesday, May 1, 2019
By dreeves

Bug report

It’s funny how universal it is for users (including programmers, including myself) to gravitate so strongly to “it’s probably just me / my crappy phone / my timezone / me not reading the webcopy / me not being deserving of love or working software / etc”. It might be an impulse to be kind and not blame the pitiable developers. Or it could be the fear of submitting a bug report that isn’t and feeling foolish.

Of course rationally it’s much better to just submit it and if we get to close it as PEBKAC or could-not-reproduce or WONTFIX or whatever that’s A++ for us and definitely still valuable to have in the bug database!

Now I face a dilemma.

I want to tell you about Proper Bug Reports, because it’s a thing worth knowing, except that it’s totally at odds with the point of this entreaty. Because what probably overwhelms the above reasons not to report bugs is simply that it sounds like a hassle. So reading any further will only make it sound like more of a hassle.

And so let me beseech you: First just tell us something conceivably buggy happened. “When I submitted a datapoint just now the yellow brick road seemed like it turned purple.” Whatever it is. Even if probably you hallucinated (it happens).

Go on. We’re over at mashing refresh waiting for you.


🎶 elevator music 🎶


Ok, at severe risk of making the perfect the enemy of the good, we shall now tell you about Proper Bug Reports, which are like so:

A Proper Bug Report

Steps to Reproduce

  1. Create a new Do More goal at a rate of 2 whatevers per week
  2. Go to advanced data entry
  3. Enter a new datapoint for today with a value of 800080 (the hex code for purple) and comment “#color”

What You Expected

That the datapoint would be plotted way above the yellow brick road and for the yellow brick road to be yellow.

What Actually Happens (AKA WTF)

The datapoint is plotted fine but the road is purple for a second before reverting to normal!

That’s it! It’s not a real example (I assume — I didn’t try it) but it would not be the most gobsmacking bug report we’ve seen if it were. Also, those three pieces of a Proper Bug Report — steps to reproduce, what you expected, what actually happens — are from Joel Spolsky and I think are pretty standard in software engineering. Feel free to make the day of the creators of any software you use by reporting a bug in that format!

UPDATE: We originally listed the three pieces as “what you did”, “what you expected”, and “what you saw” but that misses the most important point of Proper Bug Reports. It’s not just the list of steps you took, past tense. The idea is to start from scratch and see if you can make the bug happen on command, writing down each thing you do along the way.


Image credit: “Bug report” by Prettycons from the Noun Project with our own feeble attempt at Latin thanks to Google Translate

Tags: , , , , , ,