Error codes

Thursday, March 22, 2007 in Uncategorized

I’ve just discovered Coding Horror (thanks to a link in Creating Passionate Users). It seems like it could become another of my favourite blogs.

Reading it, I landed at a post titled Error Codes Must Die and liked it, although I disagree with that because moderately complex software needs a way for “speaking” with the creatures that support it / use it… whichever language they speak. If you receive an error message in your native language and try to google for it (supposing your native language is not English), your chances of finding a solution are small (compare the results for this error in English and Spanish). Googling for the error code is always better.

Things might be different when the message is for a non-technical user and the user can actually do something about it. For example, appending an error code to a message like “There’s no space left to store the file, please choose another location” makes no sense. However, if that message were logged to a file as the result of internal operations and (maybe) translated to another language, the error code would make more sense.

All in all… although I like error codes, I think that error messages should follow the rules described on the article specially when displayed to the user:

Be Polite
Never forget that an error message box is the program reporting on its failure to do its job, and it is interrupting the user to do this. The error message box must be unfailingly polite. It must never even hint that the user caused this problem, because that is simply not true from the user’s perspective. The customer is always right.

The user is not expecting the error. In fact, the user expects nothing to fail. If the VCRs stills works (even when no one uses them nowadays), the microwave still heats anything inside… why should this high-tech, expensive computer running this expensive software fail?

Be Illuminating
The error message must illuminate the problem for the user. This means it must give him the kind of information he needs to make an appropriate determination to solve the program’s problem. It needs to make clear the scope of the problem, what the alternatives are, what the program will do as a default, and what information was lost, if any. The problem should treat this as a confession.

That’s something we (programmers, designers, QAs) tend to forget. The fact that we know or guess the internals of the software does not mean that the user will. NullPointerException is meaningless to the user (it is also usually meaningless for the developers alone).

Some times we try harder: The specified resource could not be allocated. What resource? Allocated where?

In general… include in the error message enough context, even if it is implicit by the code leading to the error, because the user will not read the code.

Be Helpful
It is wrong for the program to just dump the problem on the user’s lap and wipe its hands of the matter. It should directly offer to implement at least one suggested solution right there on the error message box. It should offer buttons that will take care of the problem in various ways. If a printer is missing, the message box should offer options for deferring the printout or selecting another printer.

This is my favourite.

If the person who designed / implemented the software does not know what it should do… how do we expect the user to know?

The decision should be, for the most part, on the software. The user should only need to make a simple decision, like deleting some files and saving again, or choosing another device.

On the other hand… if the designer / coder knows exactly what to do… then do it. I’ve seen applications with error messages in the line of “You can’t select that, it is already selected it, haven’t you noticed?” (actually, the message was way shorter and not so personal)

 

Advertisement