Application error messages, write good ones and make sure they are seen!

In 1995, a cruise ship ran aground because of insufficient error handling. Well, kind of. That is not the whole story but for the purposes of this article it boils down to two reasons why the ship's pilots didn’t know that they were not where they thought they were.

The alarm that sounded was too weak to be heard.

The error message was a cryptic acronym that they didn’t know the meaning of.

Why You Should Have Well Written Error Messages For Your Website Application

While developing software most of us aren’t going to have to worry about our lack of proper error handling causing a ship with 1500 souls on board to wreck and possibly end in tragedy. However, we still can contribute in general to human suffering and hurt the bottom line when we fail to write good error messages that can be noticed.

It is worth noting that while the principles below can be applied to actually state the error upon user input validation, we are mostly going to be discussing exception error handling going forward. Let's extract out two general principles from the above cruise ship example to help us implement better error handling.

Error messages need to be noticed

This should be pretty obvious but is an often overlooked requirement. The utility of this principle should be self evident. If bad things are happening that hurts the user experience while users use your website or application, you want to know about it so you can fix the problem. This has become a lot easier with the rise of the many exception logging services out there. At Left+Right we use the exception logging that is built into our project management application. By doing so, it streamlines the whole process of getting notified, creating a ticket and getting it fixed. Even if your project management software doesn’t have this functionality there are plenty of standalone applications out there such as https://sentry.io/welcome/ and https://airbrake.io/.

Error messages must be clearly written with the proper context

Making sure that you are getting notified is just as important. If you have ever been blessed with the white screen of death and some vague numeric error, you will know that the content of the error message(s) or lack thereof can and should be important. First, you need to think about who in the audience the message is for. In this case we are talking about exception handling so it is safe to assume that a reasonably technical person will be seeing it. If the first person who sees it is not a technical person, such as project manager or user, most definitely at some point the person fixing the problem will be.

We also need to take into account our desired outcome so the context of the problem is going to be important to us. The general template that we like to follow is: 1 - display a unique error message that succinctly summarizes or names the problem; 2 - any context that will help diagnose the problem; and 3 - a backtrace for your technical team to use for quicker resolution.

We know that adding the proper error handling when having an application or website built can potentially be a pain for your tech team writing the code, but it often pays off many times over down the road when confronted with the challenge of diagnosing a problem. Error handling and implementing good error messages is something we practice as part of writing beautiful clean code. By doing so, it can turn 2 hours of staring into the metaphorical coding abyss, into 15 minutes of joyful tweaking. (Ok, maybe not joyful but at least it won’t be agony and you or others won’t want to throw their computer at the wall.)