Rob Wilkerson

I write less code than I used to (particularly during the daylight hours), but I inherit a lot of code and I review a lot of code in addition to that which I still write. Today I read something that reminded me to write about a trend - or maybe it's an oversight - I've noticed in the last few years. It seems that a lot of developers are afraid of errors. Somewhere, somehow, it seems like it became the norm to create "bug-free" software by masking bugs and failing silently. Why? Or, more assertively...stop that.

Contrary to popular belief, errors are user-friendly (at least in the long run). Errors are certainly developer-friendly. In almost every case, the latter begets the former, I've found.

I've spent hours of my life on the phone with customers attempting to articulate some cryptic, unexpected behavior in their own vernacular expressed through their perception of events. It's irritating and frustrating for everyone involved, but it's not their fault. If the software I've created or inherited hasn't provided them with a more precise avenue by which to relay the problem - a clear, concise error message - then this is the only means I've allowed them. This will not end well. Not for anyone.

Users are using software for their own reasons and their reasons almost never include carefully monitoring action sequences in case they need to replay it later for support or development staff. Really. When they're forced to do so, the result is often wildly inaccurate and littered with assumptions. Likewise, support and development staff have their own assumptions and even their own vocabulary. Sync'ing so many variables across disparate actors is challenging at best.

Many of these challenges can be easily avoided with proper error messages. Errors should be written clearly and concisely, but with sufficient detail. If detail must be omitted from the message presented to the user for spatial or security reasons, at least log the necessary level of detail. More information translates directly into easier reproduction, quicker isolation, more precise adjustments and faster turnaround time. That translates nearly as directly into a happy user.

Here are my requirements for error messages:

1. Use complete sentences.  Sentence fragments can sound terse and "unfriendly".
2. Briefly, but clearly, state the nature of the error.
3. Provide additional detail about the error.  This might include where it occurred, when it occurred, the previous action, etc.
4. Offer a few common, known causes of the error (if applicable).
5. Provide the details of a workaround (if any).

The first two requirements are mandatory.  The third is highly recommended, but may be logged rather than displayed.  The last two are optional largely because they may not be applicable.  Adding this level of information, though, gives the user a sense of empowerment and is generally well received.

Most (reasonable) users I've encountered don't mind errors (to a point). When errors occur, most genuinely try to provide as much information as they can and are even willing to work with support and development staff to reach a level of comfort that the problem has been clearly expressed. Articulate error messages bring that process to a happy conclusion much faster by removing ambiguity.