What style do you use for exception messages?

Question

In writing the code that throws the exception I asked about here, I came to the end of my message, and paused at the punctuation. I realized that nearly every exception message I've ever thrown probably has a ! somewhere.

throw new InvalidOperationException("I'm not configured correctly!");
throw new ArgumentNullException("You passed a null!");
throw new StupidUserException("You can't divide by 0!  What the hell were you THINKING???  DUMMY!!!!!");

What tone do you take when writing exception messages? When going through logs, do you find any certain style of message actually helps more than another?

Answer 1

Taking responsibility, even when it really was the user's fault, is the best option I've seen.

Things along the lines of "I can't find the file you wanted, would you check to see I have it correctly?" or "Something went wrong. Dunno what, but the only way I can get fixed is by stopping. Please restart me."

Answer 2

Just be matter of fact. Include all the information you're likely to need when debugging, but no more than that.

The only time I'd include an exclamation mark in an exception message is if it indicates that something really, really bizarre has happened. Most errors aren't really bizarre, just the product of an incorrect environment, user error, or a simple programming mistake.

Answer 3

I try to mirror the tone, grammar and punctuation style of the framework against which I'm coding. You never know when one of these messages might actually make it out in front of a client or user, so I keep everything professional, non-judgmental and specific enough for troubleshooting -- without being so specific as to give away any security issues in the code.

I avoid exclamation marks in all strings (UI and exception) like the plague, except (ocasionally) in my unit tests.

Answer 4

Concise, detailed and little redundant information (i.e. ArgumentNullException obviously involved a null).

But here's the best i've read for a while, first answer to this.

Answer 5

I wouldn't use exclamation marks too much. They express too much, think about the fact that "No disk in drive!" can be read as "No disk in drive you crazy user." ;)

I think that it's wise to throw exceptions that contain internationalized text. You never know who will use your code, catch your exception and display the text to the user. So that would be:

throw new MagicalException(getText("magical.exception.text"));

I also recommend wrapping the underlying exception (if you have one) when throwing it. It really helps debugging.

Don't think that runtime exceptions won't be seen by the user. If you are logging to a file appender some curious user might just open the log and peek into your dirty secrets.

Answer 6

A conversational tone in system messages makes the software look unprofessional and sloppy. Exclamation points, insults, and slang don't really have a place in polished exception messages.

Also, I tend to use different styles in Java for runtime exceptions and checked exceptions, since runtime exceptions are addressed to the programmer that made the mistake. Since runtime exceptions might be displayed to end users, I still "keep it clean," but they can be a little more terse and cryptic. Checked exception messages should be more helpful, since it may be that the user can fix the problem if you describe it (e.g., file not found, disk full, no route to host, etc.).

One thing that is helpful, in the absence of a specific field on the exception for the information, is the offending data:

throw new IndexOutOfBoundsException("offset < 0: " + off);

Answer 7

I tend to work my exception messages into the exception themselves. E.g. a file_not_found should say "file not found". Specific data should only be included if the user can't figure it out; in this case, the user knows the filename, so I don't add that data. Formatting can be done by whatever outputs the information if necessary, so I try to make them as friendly to reformatting as possible.

Answer 8

Polite, terse, simple, specific. Often, including state values in message is helpful.

Answer 9

I find the most helpful messages provide:

• A consistent format that makes it easy to understand what they're telling you.
• A time stamp, so you can get a feel for the dynamics of your program.
• A terse summary of the error. If you provide tech support, add an error code for quick identification.
• An explanation of what went wrong, differentiating between an invalid user input and a coding error.
• Detailed information, including the line of code or values involved.

And most important:

• They tell the user how to fix the problem.

Example:

Error 203 (Timeout) in commit.c line 42:
Unable to save salary data for user 'Linus' to database at '10.10.1.21'
after 1500ms.  Verify database address and login credentials.

One of the hardest lessons to learn is that your users are far less interested in the internals of your code than they are in getting their jobs done. Make it as easy as possible for them to do their jobs, and you've added tremendous value to your software.