Error Messages

I have written a number of libraries that are frequently used, and I have yet to find a pattern for error messages that I am completely happy with.

Let me tell you about a few of my thoughts on this.

I have found that there are two parts to an error, the code and the message. The code is a numerical value, and the message is an expression that you expect a human to read.

Error codes and messages do not have to map one for one.

You only really want to provide a specific error code if you believe the developer who is working with your code can do something about the error.

I've definitely gotten myself into the trap of creating a dozen or so error codes that all relate to how a host has failed a connection. In almost all cases of a connection failure there is very little that the end user of the end user of the library can do.

While one error code might be fine, you should create specific error messages which provide more information for an end user to diagnose a problem.

The developer who is looking at the error will appreciate the message. It might make the difference between someone spending five minutes, instead of five hours diagnosing the problem.

Never return an error message that is just a number.

No one wants to try to figure out what "error 13" means. A number tells me nothing, and while I could google the number, that is an extra step I don't want to have to take each time I look at a problem.

If you need a paragraph to explain the error, make the error searchable.

If a developer wants more information on the error, they will search for it. Make this a very simple process. It drives your users to your website. This may sound obvious, but I continue to meet people who haven't realized this.

Do not map to ERRNO.

Mapping to ERRNO. ERRNO is not very flexible, and it comes with the baggage of a preconceived notion of what the error means (which does not map across operating systems).

Give yourself enough information to diagnose a problem for the end user.

In the last few years I have taken to embedding the line of the code, and the file that the error was in, every error messages. This has allowed me to better support software that I write by creating context for me. An error is not only a tool for the end user, it is a tool for you to provide support.

Consider the case that multiple failures may occur.

Sometimes you don't have one failure in a given context, so try to store up all of the errors that occur. If you can, design your error system so that you store all of what failed.

In the end,...

Be consistent. Format your error codes and messages in a consistent manner. Make sure that if someone wants to, they can parse them in batch. Never under estime the creativity of an end user armed with a regular expression.