Friendly Exception Messages are Good for the User as Well as the Programmer

Posted on October 12, 2012 by Fernando Zamora

We all know how frustrating it can be whenever a computer system doesn’t work correctly. What’s even more frustrating is when the system teases you with cryptic error messages. You know, those types of messages that might as well read “Oops, something went wrong!”. Unfriendly error messages slip by many times because they tend occur due to exceptional conditions. Many things can go wrong that may cause an exception such as any of the following:

1. A file you are trying to write to is locked for one of many reasons
2. The database system is down
3. The system or subsystem received unexpected input
4. The system failed to connect to an external system
5. The system failed to meet security requirements
6. The data is formatted incorrectly or in a format that is not expected
7. on and on

There is an almost infinite list of causes that lead to an exceptional case. Exceptional cases are just that, exceptional; it means that the software in question is not prepared to handle the situation. That’s OK a system cannot possibly handle every request.  And yes there is a lot of technical details involved in making software work.  I mean you have error codes, modules, security implementations, database connections, communication conduits, protocols, security implementations, on an on with the technical jargon.  But that does that justify relaying this technical jargon to the end user?  What a good system should do, is provide a friendly message that provides as good a clue as possible for all the stake holders of the system. The more solid and defensive that you make your code, the more specific you can be about relaying useful information to the user.

Many times programmers go through all the trouble of validating their inputs only to display very generic uninformative messages or sometimes even cryptic messagaes. Say for example that your software scanned in a bar code and as part of the validation it determined that it failed validation for one of the following reasons:

1. Bar code was not formatted correctly
2. Product in question was not found in the database

Let’s say the code was written in a way that whenever this happened the program displayed the following error:

“Error while attempting to process the input”

As a user wouldn’t you prefer a more informative message like the following?

“Unable to process the bar code because it is written in an unrecognized format”
“Unable to process the bar code because the item was not found in the master product list”

As you can see the second set of messages will help the end users in many ways. . An even better set of messages would be:

“Unable to process the bar code because it is written in an unrecognized format. The expected format dictates that bar codes must start with “A09” and end with “D09″. Barcode: 12345679 does not meet that criteria.”

“Unable to process the bar code: 3456789this item was not found in the master product list”.

The third set of messages is even better because not only do they tell you the reason, but also provide the data. This is informative because when the user reports the issue he can send that information along through the help channels.

Put yourself in the developer shoes. With the last message, it will be much easier to analyze the issue and find the root cause.

Let’s give some scenarios. Let’s say that in the invalid format case all of the products are coming from one particular vendor. With the actual value you can easier analyze and check for the failure patterns. You may discover that the vendor has valid format but that format is not accounted for in your code. Or it may be that the vendor is providing invalid bar codes. If instead all you received from the bug report is a generic error message, you will face a tougher challenge in diagnosing the problem. The more informative message also has the potential to provide a self help solution to the end user. Maybe it was the regional management office’s job to release all those iPhone 5’s for sale on the release date and they forgot to do that. Many times systems do that to prevent selling products prior to the release date.

So a message such as “The item: Apple iPhone 5 has not been released for sale. It will not be available for sale until Friday September 21st, 2012”.

So what error would you prefer? The one above or “Error while attempting to process input”.

As a user you definitely prefer the more informative message. It would save you from calling your manager and  then him calling his manager and only to find out that the product is not available for sale yet because it’s only the 19th of the October. Or worse yet it could result in tens or hundreds of unresolved calls to the help desk. All this simply because you do not have all the information to properly diagnose the problem.

As a help desk tech you would prefer the more informative message, because it would be easy enough to see that the item is not available yet.

In the other examples you, as a developer, can examine the actual values against the implemented rules or against the database.

With a message like “Error while attempting to process the input” you will have a tough job in diagnosing the issue. If you have bug reporting system like most major systems do, you will have to contact the help desk technician and try to gather additional information from the customer. You may possibly need them to contact the customer so that they can send you the actual bar code. Good luck with that, so much time may have lapsed that they may not even remember which item was causing the issue. In the mean time you may have to send your developers on a needle in haystack hunt, scouring and reverse engineering the code. Developers aren’t cheap, so every hour you spend hunting down bugs adds to your maintenance costs and slows the speed at which you fix bugs and add valuable enhancements.  If you are a developer you know that it is much harder to find a root cause without the exact data that caused the problem.

I used the word exception at the top of this post, but in reality any type of messages that prevent the user or the system from proceeding should be as informative as possible.

Before I finish this this post I will admit that there is one caveat to providing information. That is that you must also be cautious about revealing any information that will reveal vulnerabilities. Things such as revealing the full stack trace or revealing database structure are big don’ts. Hackers can leverage these vulnerabilities to attack your system. So with careful thinking and planning you can write friendly informative messages that will make everyone along the chain happy.  This means everyone, from the end user all the way down to the programmer in the trenches.

This means that everyone will be much happier.

The project manager will be happy at the efficiency of the team’
The help desk tech will enjoy the lower volume of calls
The tester, business analyst, and end user will appreciate having a clue of what went wrong.
The developer will save and extraordinary amount of time diagnosing the issue and therefore be more productive

This little bit of information seems so simple and even redundant, but I have personally witnessed this fallacy in many systems. Many of those systems are from very well respected companies and products. That’s my main motivation for writing this post. Hopefully it will motivate you to think thoroughly whenever you are faced with creating a new message for the end user.

Before I close out this post I’ll leave you with some examples:

Bad: “Password Invalid”
Better: “Password must contain two numbers two uppercase, two lowercase characters, must be at least 15 characters and cannot be one of your last 10 passwords used”
Best: “Your password must contain two uppercase characters”

In the first case you may not know why the system is rejecting your password. With the second example you at least know the rules so that you can make sure it does not violate any of the rules. The problem with the second option is that if the program has a bug you won’t know for certain which rule is in violation.
With the best option, you will know exactly which rule is failing (you display the exact rule that is being violated0 and if there is a bug in that logic, the programmer can hone in on fixing that particular rule.

Bad: “Error occurred while accessing your retirement account”
Better Options:
“It appears the retirement account information provider system is down. The client failed to connect”
“Received the information but an error occurred while processing the data. The system was unable to recognize the format in the following line: xyz”
“Your account has been locked by the retirement account information provider. Please contact their customer service at 1-800-… to unlock your account. After that you can try again”

In this case if you get the generic error you will not know the reason you are unable to connect. As you can see, it can be any one of three reasons. This may hinder customer service from helping the end user because they will not know the cause of the failure either. As far as the programmer is concerned, it will be a real challenge in troubleshooting the issue with the first error.

I hope that this information will help you design better systems that are easier to diagnose and maintain.


Leave a Reply

Post Comment

Connect With Us

Recent Posts

A Guide for Learning Design Patterns

July 28th 2016 by Fernando Zamora If you’ve been writing code for more than a year, you might have h...

Read More

Using UML to Analyze Legacy Code

June 30th 2016 by Fernando Zamora For every programmer out there creating brand new code and working...

Read More

Python vs. Other Languages

April 29th 2016 by Fernando Zamora For the last two months or so my fellow McLane Advanced Technolog...

Read More

Naming Your Adapter When Implementing the Adapter Pattern

October 19th 2015 by Fernando Zamora At some point in your project you may need to use a third party...

Read More

10 Methods to Help You Debug Legacy Code

September 24th 2015 by Fernando Zamora A large majority of the work we do in our project is to fix r...

Read More