There are few things that annoy me as much as error messages in software. Error messages are up there on the annoyance ladder, with wasps, vuvuzelas, and someone buying the last bottle of Yop right before you.
Error messages generally suck hairy donkey balls. Often, they fail to display the information you need to fix the problem. They are not helpful enough.
For example, imagine you’re playing around with rtorrent, and you want to move all completed torrents to a certain location. To do that, you put the following – rather complex! – line in .rtorrent.rc (line split for readability):
system.method.set_key = event.download.hash_done, move_complete, "execute=mv,-u,$d.get_base_path=,/torrents/finished/; d.set_directory=/torrents/finished/"
You fire up rtorrent and download something. After that, you notice that the downloaded file has not been moved to the right location. So, you look at the log, and you see this error:
(18:05:34) Download event action failed: Bad return code.
Well, “thanks”, rtorrent. I already knew that something has failed. But could you please tell me the command you executed, which failed? And the error message that the command generated?
Error messages in Windows applications often seem to be of the type “something went wrong”, without explaining what went wrong or how to fix it. Take a look at this one, taken from The Daily WTF:
Which process? Which file? Which other process? Without this information, there’s not much the user can do.
I suspect that some of these unhelpful error messages are caused by the laziness of the software developer. I am a software developer myself, and during peer reviews, I’ve often seen error messages like “This package is not active” or “Component does not fit“. Not so helpful at all.
These two error messages could have been improved much, for example “Package <type> <id> is not active, but <state>.” or “Component <type> <id> (<description>) does not fit in package <type> <id> (<description>).”
So, if you are a software developer, and you are writing an error message, try to make it as useful as possible. Imagine running your software and encountering the error you are currently pondering about. How would you go about fixing the error? Which information would you need to trace the problem and solve it?
Then, put that information in the error message. People who use your software will be less annoyed if your programs encounters an error, when they see that the error message is helpful. If you receive a bug report with an accurate, useful error message, you will be able to find the bug much faster. And you will thank yourself for being so smart, once you run into your own error some days, weeks or months after you’ve written it.
(While writing this, I found a blog post by Kevin Ertell which has a similar message.)