Effective Bug Reporting

“It doesn’t work”, and other ineffective bug reporting techniques in an age of agile development.

When I started my software career in the late 1990s, the ideas of bug reporting weren’t new, but in the 20 years since, much has changed with agile development, newer software systems and ideas about tracking software and tasks.

In particular, there was the following seminal classic by Simon Tatham back in 1999:

Even now, (or perhaps, especially now), Simon’s comments remain relevant, and this has always been the article that I’ve referred people to. However, after years of software development, and working closely with QA engineers, and with reference to newer reporting systems, it’s time to make my own version, especially since I haven’t been able to find anything that is as comprehensive as what I want to articulate here.

What is a bug?

First, I’d like to turn the paradigm on its head and explain that when I say “bug”, I’m definitely not limiting the meaning to a software fault of the kind we have traditionally thought about.

In some reporting systems, it’s called a “story”. This is deliberate, and in keeping with what I’m about to assert. To this end, you may interchange “bug” with “story” or “task” or whichever nomenclature your systems or development style uses.

Here are some examples of what a bug or story might be:

This is list is naturally incomplete.

Here’s my point — a bug or story is something to be done — it describes the current situation and what the outcome might be. Put differently, it could describe every single step of software development — the specifications to write, testing to be done, documentation to write, faults to fix, etc etc. Now, to seasoned software engineers, this is probably obvious, but for many engineers, I know it’s not necessarily so, so I’d like to repeat it one more time:

A bug/story is a description of a task to be done and tracks its life cycle.

Clear on that? Good. Then the rest should make sense.

What a bug isn’t (In my opinion)

But they can be…

Bug Reporting Systems

Here are some of the common bug reporting systems around:

Why bug reporting systems can be bad

There are lots of reasons bug reporting systems can be intrusive or irritating. Like much, it’s a matter of balance.

The Importance of Titles

“A good bug title states something which is true, but you want to be false”.

Not my quote, but a good rule of thumb. Of course, not all bugs fall into this category, but an effort here pays dividends upon review of a bug much later.



The point here is that poor titles are misleading, cause miscategorization and misunderstanding. So, your aim for a title should be as terse as possible, but also as accurate as possible.

What a good report might have

Other guidelines


For practice; come up with some bugs relevant to your situation. Make sure it follows the guidelines I’ve outlined.

Have a peer review it, who’s familiar with the problem:


Not everything here works for everyone. But I think most of it does. But good guidelines adapt like good bugs. I expect what I wrote here won’t be as correct as it was in a few years, just as Simon’s is no longer complete.

Good luck!



Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store