While this is more of a written language issue than a coding one, it is something that programmers must do in circumstances where copy is not provided by a client or someone else. Any examples of error messages, good or bad, are welcome to make the point.
I briefly searched and could not find a dupe thread. Ok, have at it. Thanks, all.
First thing to ask:
Good means very different things for end-users and other developers.
Do you mean user-facing or in a log file for admin/dev staff?
I think these are important, in general:
I think all of these are important, but the prominence will change depending on the audience (as dmckee points out). Another tip (in general) is to answer the 5 W's (who, what, ... etc)
For end users: Tell the user what to do. Should the user change some input value, retry in 5 minutes or call support?
Example:
"Sorry, the file could not be opened. Please check that the file is not already opened by another program and try again."
If there are additional details that would scare the user such as an error number or something else only a developer would understand, don't show them. Write them to a log file, or have a details button that can be pressed to get to them.
I'm assuming you're talking about showing error messages to users in message boxes or on screen.
I work at a software security firm, so my answer may be significantly different from some of the above answers.
A good user facing error message is:
Balanced between being generic and specific - You want to give the user enough information that they can correct their error and move on, but keep in mind that an attacker could use these same error messages to attack your site. A good example of this is a login control in which an error message is returned “incorrect password for user joe” or “user joe does not exist in this system” this tells the attacker that they are on the path of discovering correct users. Which when you have neither a username or a password is half the battle.
Tells the user what went wrong – again this is balanced between generic and specific. A user never needs to see an ODBC error message, but it might be helpful for them to know that the error was your fault and that they should try again in a few minutes. Tell the user what they can do to help – if you have a backend logging system (which you should) log everything you think will be useful, then generate an ID that you can provide to the user so they can call or e-mail you and tell you exact repro steps. You could also automate this by exposing an bug submission form when an error happens.
Be consistent – use an error lookup table to ensure that all your errors are the same (for the same problem) and that they are well written. Typos, spelling mistakes and grammatical errors cannot be tolerated in production software.
To what was already said I would add:
Remember above all that the end user does not care about the technological nitty-gritty. Only whether it works. When it doesn't work, he or she only cares about its effect on what they are trying to do. A useful error message should stay focused on the what, not the why.
Error messages should:
From a technical support point of voice, it's also important that error messages be unique. If a user can generate the same "file could not be opened" error in six different ways, it makes it difficult for technical support people to figure out exactly what the user is doing. So, error messages should be unique for each different kind of error and if possible supply an error code or number so that support people know where to look for the problem.
We've found that when error messages include an error code, it helps with technical support. When users report error messages back to support people, they often mix up or mis-report verbal error messages. But, if the message includes an error number they are very good at reporting the exact error, like "I got a 8512 error when I tried to print a report."
When possible, it also helps to keep a log of errors. Many times users will report errors when they tried a particular operation, but they won't remember exactly what the error was. If there is an error log that can be consulted by technical support people, it makes it far easier to determine the problem.
To write good error messages, you need to think about each audience. Once you understand the audience, it's much easier to design the error messages.
First, requirements for end-user messages:
Next, requirements for support technician messages:
Finally, requirements for support developer messages:
An example of an error message that's very bad for an end-user, but that might be reasonable for a developer, is "Latency cache collided with outbound headers." :-)
It's usually worth pointing towards a common reason for the problem as this will help the user in 99.9% of the error cases.
For example we have two directions for initialisation issues. One catches configuration exceptions which states:
"A recognised exception occured. This may be an issue with the configuration"
and another for unexpected:
"An unexpected error occured."
Then depending on the setting (dev switch on or off) we either output dev info or more end-user-friendly info ontop of that.
There can be a few different contexts here to note(though I'm sure this has been mentioned over and over again):
1) If we are talking about a website having to give an "Oops, something bad happened," message then there should be simple language to tell the user that an error occured, please try again and if there are still issues to contact support at blah blah blah...
2) If we are talking about logging an exception thrown in code for sys admins and developers to read then the matter becomes more of taking the exception's message and stack trace to be recorded in either a log file, an e-mail, or the event viewer so that it can be handled differently depending on how urgent is it that someone looks into this.
3) If we are talking about writing the message for an exception then my suggestion is to clearly note what kind of error condition was met, e.g. is there a null reference where there shouldn't be or is there something worse like a file that should exist is missing, along with the severity of the error, e.g. can the application keep running or should it exit to an error page in this condition.
Error messages are for end users and also for those who have to maintain the code
First for end users, tell them what to do. This can simply hit enter to continue, to try again, to close and restart, to reboot the PC.
Second for maintainers, include as much information about the error as you can. There is never too much. I personally prefer a log file for this instead of an error message. Even better is to include a way for the end user to e-mail you the log contents from the application.
Obviously error prevention is best. Always provide the user with enough cues to successfully complete tasks (i.e. explain required formatting on data entry fields). However, "To err is human..." and (by applying the principles of usability to errors in a web application) forgiveness is the goal.
There are three essential functions to error messages:
1. Get attention - first, to ensure the effectiveness, the user must see it
2. Describe error - inform the user of what went wrong
3. Suggest recovery - give useful suggestions to fix the error and continue
All that being said, I would love to compile something with more detail, and especially with examples of good and bad error messages.
If you can tell the user what to do then please consider doing it programmatically. In my opinion, error messages should only appear if the program is in doubt about what to do. Think about why you decided to just fail: maybe not taking the responsibility to try and recover? Maybe the user can do it much easier? Maybe the user has to decide which solution to take? Maybe you thought that it should never happen (do not forget to tell the user to contact the support or the programmer in this case)?
One thing that can damage my nervous system is when an error message uses the word OR. "File not found OR no permission OR disk full OR your dog has a bad headache OR..." A user really needs to know which one of the possible error causes happened. Programmers please avoid ORs in error messages.
Do not copy error messages to different places of the code. If a user sees the message in your program and sends feedback, a luckier case is when you can fathom what your error message meant. The less lucky case is that you at least can grep the entire source code and find the place where the program crashed. If you find the same message multiple places you cannot help yourself.
Oh and don't forget to mention possible consequences: "Squirrel Prevention System quit working. Anything stored on your hard disks may be randomly modified by squirrels." "The Squirrel Prevention System quit working. Squirrels will be prevented by the General Prevention Framework instead." There is a difference in the severeness.