Error Message Text - Best Practices

Question

We are changing some of the text for our old, badly written error messages. What are some resources for best practices on writing good error messages (specifically for Wind

Answer 1

In terms of wording your error messages, I recommend referring to the following style guides for Windows applications:

• Windows user experience guidelines, and specifically the section on error messages here.
• Microsoft Manual of Style

Answer 2

1. Avoid identical error messages coming from different places; parametrize with file:line if possible, or use other context that lets you, the developer, uniquely identify where the error occurred.
2. Design the mechanism to allow easy localization, especially if it is a commercial product.
3. If the error messages are user-visible, make them complete, meaningful sentences that don't assume intimate knowledge of the code; remember, you're always too close to the problem -- the user is not. If possible, give the user guidance on how to proceed, who to contact, etc.
4. Every error should have a message if possible; if not, then try and make sure that all error-unwind paths eventually reach an error message that sheds light on what happened.
   
   I'm sure there will be other good answers here...

Answer 3

Support for multilanguage applies for all kinds of messages, but tends to be forgotten in the case of error messages.

Answer 4

A good error message should:

• Be unobtrusive (no blue-screen or yellow-screen of death)
• Give the user direction to correct the problem (on their own if possible, or who to contact for help)
• Hide useless, esoteric programmer nonsense ( don't say, "a null reference exception occurred on line 45")
• Be descriptive without being verbose. Just enough information to tell the user what they need to know and nothing more.

One thing I've started to do is to generate a unique number that I display in the error message and write to the log file so I can find the error in the log when the user sends me a screenshot or calls and says, "I got an error. It says my reference number is 0988-7634"

Answer 5

For any user input (strings, filenames, values, etc), always display the erroneous value with delimiters around it (quotes, brackets, etc). e.g.

The filename you entered could not be found: "somefile.txt"

This helps to show any whitespace/carriage returns that may have sneaked in and greatly reduces troubleshooting and frustration.

Answer 6

For security reasons, don't provide internal system information that the user does not need.
Trivial example: when failing to login, don't tell the user if the username is wrong or the password is wrong; this will only help the attacker to brute force the system. Instead, just say "Username/Password combination is invalid" or something like that.