Design Guidelines Update: Exception Message Guidelines

It has become clear to me recently that we could be doing a better job with exception messages. I took these guidelines from a set that the UE team on the .NET Framework uses. Love to hear your comments, issues, and suggestions.

7.3.2 Exception Error Messages

Do provide rich and meaningful message text targeted at the developer when throwing an exception

Annotation (BradA): Unintelligible, incomplete error messages are the most common reason why users contact support. Error messages that precisely and lucidly describe the problem, the probable causes, and the solutions or workarounds help users understand why the error occurred, how to fix it, and how to avoid it in the future. In addition, all exception strings are localized, which makes it especially important to deliver messages that are clearly stated and complete.

Do localize exception messages

Annotation (BradA): Many developers that use the .NET Framework are non-English speaking. We localize our entire documentation set (including the huge API reference). Localizing the error message helps non-English speakers feel more comfortable on our platform.

Do use grammatically correct exception messages. Make the assumption that code may present the user with the exception message.

Each sentence in a description string of an exception should end in a period. This way code that generically displays an exception message to the user does not have to handle the case where a developer forgot the final period, which is relatively cumbersome and expensive.

            Do provide useful information that helps the user diagnose the problem. For example, rather than using “Bad link,” try “Link target does not exist”

            Do be precise. For example, “Missing file name extension” is better than “File not found.”

            Do describe the problem. For example, “Disk full” is better than “File error.”

            Do use third-person, simple present or past tense, and active voice.

            Do use a neutral tone. For example, change the tone in “Bad input” to “Command is unrecognizable.” to avoid blaming the user.

            Do start with search-relevant words. Use passive voice or more complex construction if necessary. For example, “Log file {0} is full.” is preferable to “{0} log file is full.”

            Do use complete sentences. For example, use “Binding is too long.” rather than “Binding too long.”

Do not use exclamation points. Notice the difference between “Command is unrecognizable!!” and simply “Command is unrecognizable.”

Do not personify (imply that programs think or feel). For example, “Node parameter cannot use Windows NT protocols.” is better than “Parameter node does not speak any of our protocols.”

Do not start with an article or variable. Use searchable words at the beginning instead. For example, “Log file {0}is full.” is preferred to “{0}log file is full" or “The {0}log file is full."

Do not use quote marks for emphasis.

Do not provide security sensitive information in an exception message.

Comments

• Anonymous
  January 28, 2004
  The comment has been removed

• Anonymous
  January 28, 2004
  The comment has been removed

• Anonymous
  January 28, 2004
  The comment has been removed

• Anonymous
  January 28, 2004
  Identifier
  
  I specify the use of identifiers for exceptions in my application architectures. But such a requirement is probably best left at the application/enterprise level rather than the base system level. The only reasonable way to have globally unique error codes would be to use guids, but they would be very difficult to communicate on a support call or KB-type look up.

• Anonymous
  January 28, 2004
  What about a guideline about allways specifying which resource caused the exception, if any?
  
  So instead of:
  "File was not found."
  
  then:
  "File 'c:myfile.txt' was not found."
  
  It makes it a lot easier to troubleshoot.

• Anonymous
  January 28, 2004
  The comment has been removed

• Anonymous
  January 29, 2004
  In RE: Do not personify (imply that programs think or feel).
  
  I believe the term you are looking for is anthropomorphize (Although Word does think they're synonyms). Great list.
  
  I'd also suggest not showing compiler errors to the user. For example, something like "a connection couldn't be made to a requested resource" instead of "resource error: object reference not set to an instance of an object".

• Anonymous
  January 29, 2004
  The comment has been removed

• Anonymous
  January 30, 2004
  Localization
  
  I have written a framework to support different languages that interops with the event log API the way it wants to (It also supports multiple languages). It would be alot easier to dump that support, frankly. There IS one area where it is important, though.
  
  I agree that end users should not see the errors: All consumer code oriented exceptions should be translated by the UI layer -- another reason to require an identifier. However, internal exceptions have TWO audiences, not just developers. Most internal errors get logged somewhere so that a sysop can look at them. Sometimes it it a coding problem and simply gets passed along to the developers. However some internal errors, i.e. non-consumer code errors, are environmentally driven and is the responibility of the IS admin to fix. These SHOULD be in the language of the installation culture.

• Anonymous
  February 05, 2004
  I have a question, how was the decision for these 2 classes ctor parameters made...
  
  Constructor for ArgumentNullException
  public ArgumentNullException( string paramName, string message)
  
  Constructor for ArgumentException
  public ArgumentException( string message, string paramName)
  
  

• Anonymous
  February 06, 2004
  Provide extended messages (for certain exception types) -
  for e.g.,
  Also see KB Article: Q12345 or 76543:Info
  (with the numerical code containing the hyperlink as a link label)

• Anonymous
  February 20, 2004
  For my own reference, I thought I'd compile a quick list of design guidelines added by Brad Abrams, et al.

• Anonymous
  March 05, 2004
  I had an SMTP mail issue in ASP.NET the other day. Try a search on 'Transporten kan ikke koble til serveren' or something like that, actual wording is forgotten. If I had the English equivalent 'The transport failed to connect to the server' it would be so much easier. I found it by coincidence when I searched on something else.
  
  So localized system messages is not very helpful. I am a developer and didn't understand it, I don't think any local users would do either. Which comittee thought this was a good idea, anyway?

• Anonymous
  January 13, 2007
  I was looking at BradA's blog again today and I saw his annotations for proper exception messages. This

• Anonymous
  February 21, 2007
  The comment has been removed