Steinbach's guideline is a well-known maxim in the tech world, but I have a variation on it which is at least as important (and much more serious):

There was a time when we had to make due with cryptic error codes, but it's not 1960 any more. Memory, disk, and bandwidth are cheap these days. We can afford to write programs with the ability to report clearly and accurately what has gone wrong rather than requiring the user to look it up in a manual somewhere or, worse, try to guess what happened.

Earlier today, I was posting a comment on a major website, but, when I attempted to submit it, the site replied:

(Error code changed to protect the guilty. Their identity isn't relevant to my point.)

This is a horrible error message, as it gives no information about why my submission was not accepted. Was it an issue with the content of what I submitted? Did their database server fall over? Had they received too many submissions in too little time from my IP address? A web search on the error code suggested all of these, plus a couple more, as possible causes for that particular error code from this site.

There was no clue at all as to the actual cause, aside from a suggestion that I should run a virus scan, then try again later, just in case a rogue piece of malware on my computer might have somehow caused a problem on their server - if it even was a problem on their server at all rather than a deliberate attempt at cryptic rate limiting. (If it actually is possible that malware on my computer could have broken their server, then they have bigger problems than poor error messages and need to learn something about input validation first.)

Much better would have been something like

or

Note that a good error message does not necessarily have to go into exact detail about the problem. There are legitimate reasons why you may not want to divulge those details - explaining exactly why a post's content is unacceptable would make it easier for someone to comply with the letter of your rules while violating their intent and telling an attacker what exact database error they caused could help them to crack your system - but you should provide enough information for the user to know whether the error was caused by their actions or by something else and whether there is anything they can do to resolve or work around the error.

Of course, the best way to handle errors is to not allow them to occur in the first place. In the first of those "better error message" examples, the server should have already known in advance that the user had used up his posting allowance for the day and not given him a link to create a new post at all, rather than letting him type up the post (which, if it's well-thought-out, may involve considerable time and/or effort), only to reject it when it is submitted.

Oh, and the "temporary" error that inspired this post? Several hours later, I'm still getting Error Code 23.

Originally posted to NomadNet blog on Feb 4, 2009