Software Bugs – The importance of useful error messages

We have all seen are share of error messages that are completely useless.

I have definitely seen my share (the first ones that I remember “Abort, Retry, Fail” & “PC Load Letter”) and I am sure I have contributed my share in the applications that I have written.

The importance of useful error messages is under-scored by this piece of news of how emergency alert messages were not sent out to the residents of a city when a tornado was eminent (Errors stalled warning in Fort Collins). In this case, because the user had created overlapping regions to send out alerts to, the software (Everbridge Aware) failed to send out the alert messages to the city’s residents. But because the system did not provide the user with a useful error message, the user was unable to correct the issue and send out the alert.

In my experience unhelpful error messages are caused by:

1. Prototype code entering production system and never having been refactored and revamped.

2. The developer did not realize that a certain operation could cause an un-handled exception.

3. The developer coded defensively to handle all exceptions, using just the generic exception class, instead of a specific exception type.

All of the above could lead to a generic error message being displayed to the user.

And sometimes the above will end up creeping into your application, because that is just the nature of the beast. It is for this reason that one should have a robust logging mechanism attached to their application (and documenting where the logs exist for end-users to find). If this had been done with the EverBridge system, then the operator might have thought of looking at the log file to determine the exact cause of the error message and taken remedial action. (This sort of behavior is common Microsoft Installers use a log file as well the system log, VLS’s Feature Analyst uses a log file as well as a real-time console window to display system messages)

Bottom line: We as developers need to be cognizant of the fact that some of our error messages might make no sense to the end user and can cause a great deal of frustration to them. Apart from using presentation guidelines in our error messages, one should also try and capture information regarding the context in which the error occurred which can be used by end users to further diagnose a problem when they come across an error message which is less than helpful.

Coding Standards and Error Messages:

Typically, Coding Standards documents ignore dealing with error messages, because that isnt really considered as an “integral” part of the developer’s job. Ideally your errror message guidelines should be made a part of your organizations coding standards document – this way, everyone will be thinking of making them usable while they are developing applications. Presented below are some examples:

From C# Coding Standards document:

19. If a wrong value found in the configuration file, application should throw an error or give a message and also should tell the user what are the correct values.
20. Error messages should help the user to solve the problem. Never give error messages like "Error in Application", "There is an error" etc. Instead give specific messages like "Failed to update database. Please make sure the login id and password are correct."
21. When displaying error messages, in addition to telling what is wrong, the message should also tell what should the user do to solve the problem. Instead of message like "Failed to update database.", suggest what should the user do: "Failed to update database. Please make sure the login id and password are correct."
22. Show short and friendly message to the user. But log the actual error with all possible information. This will help a lot in diagnosing problems.

And these ones that define the formatting of error messages (Summary of Coding Standards):

For error messages the following conventions apply:

• Provide specific error messages with all the relevant information (variables, exceptions, etc.)
• Messages start with a capital letter.
• Try keeping messages below 70 characters.
• Don't end the error message with a '.'.
• Don't use wildcard characters (* ? \) inside the error string. A search in the logs for text containing these characters are always difficult.
• Don't include newline characters in error messages.
• Quoting information is done using single quotes ('some info').
• Don't include the name of the method where the error occurs in the error message. Log systems will provide this information by itself.
• When including path or filenames in the error string, be sure to quote them. (i.e. "Can't find '/path/to/repos/userfile'")
• Suggestions or other additions can be added after a semi-colon, like this: "Can't write to 'file': object of same name already exists; remove before retrying"
• Try to stay within the boundaries of these conventions, so please avoid separating different parts of error messages by other separators such as '--' and others.