A part of a beetle collection, Melbourne museum, Australia — which for an IT Engineer looks like Jira bug tracking system :)

Write better bugs titles

Prephase

What is a bug in software?

Software bug — is a detected fact of mismatch between actual behavior of software and expected behavior based on software requirements and specifications, industry standards (like RFC, IEEE, GOST, etc.) and common sense.

What is a bug in bug-tracking system?

Bug in bug-tracking system — is a type of an issue which aims to keep all information about Software bug.

What is the purpose of bug submission into a bug-tracking system?

Purpose of a bug (in bug-tracking) submission — is to get a bug (in software) being known (to be fixed).

That’s why bug tracking system — is like a library, like a knowledge base. It holds all your “detected facts of mismatch…” — and that’s why it’s very important to submit bugs into bug-tracking system correctly. Correctly — means with a good description. Good description means “fast and easy to find”. And the most important part in “fast and easy to find” — is a good bug title. So…

What is a good bug title?

Symptom, not root cause

Good bug title tells us about precise symptom, not about the root cause.

When you face the bug, you face a mismatch between expectations and reality, you face a symptom. And symptom — is what is visible, what is clear. It’s like in illness: you might have pain in your back, but the root cause might be problems with your feet. You don’t know about the problems with your feet yet, but you feel the pain in your back.

What would you do? You will search for a solution for a “pain in the back” problem, right? And this is the first understanding to write a good bug title: write about symptom, not about root cause.

Precise symptom

“Pain in the back” — is too vague symptom. There could be tens or even hundreds of “pain in the back” issues in bug-tracking system, if we filed them this way. And the problem with such approach is that it is difficult to find if your case of “pain in the back” is in bug-tracking system already without review of almost every case.

That’s why we need to be more specific and provide more info in title, rather than just “pain in the back” or “service crashes” or “website responds with bad gateway error”. We need to add condition and situation, we need to add a context — because context of execution determines if the bug appear or not, and which way.

Take a look on this:

“Pain in a right shoulder blade when walking for a long time”

Is it much better rather than “pain in the back”? Yes.
Is it much harder to write this rather than “pain in the back”? No.

I.e., you need to think a bit more to write this — yes. But it is not that much harder. It just more conscious. And this consciousness pays you back, when you face the problem and look through bug-tracking system issues to find your case. Because bugs are much more often being read rather than being written. And the better they are written — the faster people work with them and with less number of mistakes.

Bugs (issues in bug-tracker) are much more often being read rather than being written.

Not all bugs get being fixed

This fact is especially important for great titles.

Because not all bugs get being fixed, a lot of engineers and customers can face them through their lifetime. And if bugs (issues) would be written with great titles, that could help to find them easily and precisely, then you’ll avoid duplicate bugs (issues), save your team time and energy and help to prioritize bugs higher if they appear often or started being very annoying.

Conclusion

For example, if a database throws an exception when you post a blog post and you get an error message, then write about an error message in your bug title, write about symptom, visible to the user.

I.e.:

Error message ‘500 internal error’ appears when you post a blog post for the first time

is much better than:

Database throws exception ‘unique constraint’ when you post a blog post for the first time

because database could throw errors, web-server processes might crush, etc., etc., but if no one noticed that, then it looks like “everything is fine and working as expected” from end-user point of view.

And because the bug (in software) — is a “detected fact of mismatch” then “not detected — is not a bug”. I.e. we talk here about user impact and priority that good bug title may help to determine.

And don’t worry about the found root cause with a database exception. You’ll write about it in a bug description later!

Bonus for small teams

SQA Mate test cases management system uses Jira-like markup language — which makes it easy to be used as a bug-tracking system as well.

I personally use one of SQA Mate’s projects as a bug-tracking system for SQA Mate itself! All the issues I find in SQA Mate, I submit — fast and easy — in SQA Mate project and then fix them as the time comes. It is very convenient and you don’t need Jira for that!

P.S.: if you liked this article and found it useful, please don’t hesitate to give it some claps — just to let more people to know about it!

Thank you!