How You Talk Yourself Out Of Reporting A Bug

Wednesday, May 1, 2019
By dreeves

Bug report -- Reseminata, Expectata, Resultata

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:

Defectus Demonstrandum

Reseminata (Steps to Reproduce from Scratch)

  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”

Expectata (What You Expected)

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

Resultata (What Actually Happens)

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 — or some specific seed that’s easy for others to start from — and see if you can make the bug happen on command, writing down each thing you do along the way.

FURTHER UPDATE: These days we label the three sections of our bug reports as “Reseminata”, “Expectata”, and “Resultata” because that is how big of nerds we are. “Reseminata” as in what you do to reproduce something from scratch, similar to the English word “reseminate”. Also we refer to such a bug report as a Defectus Demonstrandum. We updated the above sample and this post’s title image accordingly.


Image credit: Based loosely on “Bug report” by Prettycons from the Noun Project with adaptation by Faire Soule-Reeves and Latin help from Rob Felty.

Tags: , , , , , ,