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.