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 bright red line seemed like it turned purple.” Whatever it is. Even if probably you hallucinated (it happens).
Go on. We’re over at support@beeminder.com mashing refresh waiting for you.
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
Replicata (Steps to replicate the bug, ex nihilo)
- Create a new Do More goal at a rate of 2 whatevers per week
- Go to advanced data entry
- 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 bright red line and for the red line to be red.
Resultata (What Actually Happens)
The datapoint is plotted fine but the line is purple for a second before reverting to normal!
(And then internally we also add desiderata for the specific tasks involved or what besides fixing the bug itself needs doing, nota nebulosa for additional hints or theories or ideas for fixing the bug, cognata for related bug reports, and verbata for keywords and phrases to make the bug report easier to search for. Defectus delenda est!)
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 replicate, 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 “Replicata”, “Expectata”, and “Resultata” because that is how big of nerds we are. Also we refer to such a bug report as a Defectus Demonstrandum. We updated the above sample and this post’s title image accordingly.
YET ANOTHER UPDATE: For a while we were using “Reseminata” for the steps to reproduce the bug until we finally thought of “Replicata”.
UPDATE 2022: We changed “yellow brick road” to “bright red line”. We’re not doing that in every old blog post, just ones we find ourselves linking to often.
UPDATE 2023: We keep gradually accumulating more Latin, which I’ve now edited in to the “Defectus Demonstrandum” sidebar: replicata, expectata, resultata, nota nebulosa, desiderata, cognata, and verbata.
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.