The error of our ways

Software developers are typically judged by their ability to write code in one or more languages, and some of us can write in a dozen languages or even more. However, one side of writing good software that’s often missed is writing good error messages. Ultimately, any software can run into errors, whether because there’s a bug in it, or because the user made some mistake. However, a clearly written error message can make a world of difference between a minor annoyance and complete frustration that could, in some cases, lead to a piece of software being completely dropped.

A primary guidance to many developers when writing error messages is the obscurity factor. In their eyes, if the error is less likely to ever show up, they will invest little to no attention on making it useful. That’s where we run into error like these:

   

Or even better:

It’s unfortunate that developers often don’t realize the harm a bad error can do. While the internet has made it easier to find the source of obscure error messages and codes, if the error is obtuse enough, even the most experienced googler may not be able to figure it out. Googler, you ask? Well…even in corporations, where there’s a supposedly-qualified IT department that’s supposed to help with things, one must keep in mind that the typical user will start his journey with the 1^st tier helpdesk, manned by less experienced individuals. In such a case, their support individuals themselves will often turn to their favorite search engine to try to understand what’s up. In such a case, “an unknown error occurred” will make it very hard to locate the true source of the issue.

Another aspect to this is the whodunit. When a user runs into a problem, most of them need to understand whether the issue is something that they did, that was done to them, or that just happened. This is an important psychological factor because if the problem is their fault, many users may feel timid about calling out for help. On the other hand, if the problem is a result of something that was done to them (for example, if some server was disabled by the IT group, making the application cease to work), this could lead to much anger being developed and projected at that IT group. That, of course, may be well-deserved, but if it’s not, it’s the developer’s responsibility to make sure the message is clear about that.

Another aspect to be considered is the fixability. If the issue that led to the error is easily fixable…why send the user on a wild goose chase? Why not just tell him or her what to do right there? For example:

     

Finally, we already mentioned the searchability factor, and a unique message goes a long way towards that…but that also means that the message shouldn’t be TOO unique. For example, specifying the memory address in the error message may seem cool, but since it would typically be unique to every run of the app (yet is usually of no use to resolving it), it would actually make it hard or impossible to find a solution.