Recently, as I was writing error messages for various instances of carp, croak, warn and die, I realized that -- unlike with my code -- I've never quite settled into a consistent, personal "style" for phrasing and formatting error messages.

Some of this, I think, is a result of the error messages being something of an afterthought -- a sort of, "oh, yeah, I should throw an error if that fails" postcript, where once the die statement has hit the screen, I want to get back to coding and the error message winds up being whatever quickly comes to mind.

As I'm trying to more regularly practice test-first development, I'm trying to moderate the habit of sprinkling error handling willy-nilly as I code unless I actually document the need for it in a test script first. Or, I'm quickly coming back after a Devel::Cover run and filling in test scripts for all the untriggered error handlers.

In writing the test scripts, actually thinking about how my code should behave with an exception has me thinking more about what are good practices and good style. I thought I'd throw out a few potential ideas for a style guide to jumpstart a wider discussion:

• Target the error message at the source of the error

  • Use carp and croak for messages about parameters or other user input
  • Use warn and die for unexpected system behavior or failures that "shouldn't happen"

• Provide the line number if the error condition came from the code or a system failure to help with debugging (i.e. don't put "\n" on the message)

• Don't provide the line number if the error came from runtime input (i.e. end the message with "\n")

• Be consistent in whatever style is chosen. E.g. All fatal errors should start with "Error:" or "Fatal Error:"; all warnings should start with "Warning:"

• Start the message with a brief description of the result of the error

• Include the cause of the error by appending $! or $@ as appropriate

If a style guide was in use, a template could be used with throws_ok from Test::Exception to ensure some minimal conformity, without necessarily (unless desired) needing to check the entire error string. E.g.:

throws_ok { some_function() } qr{\AError: .+}, "some_function() error 
+handling";
[download]

What best practices have you found for error messages? Does anyone have a particular style guide within their company or team? Other than die mentioning that adding ", stopped" can help readability, I've not seen much by way of concrete recommendations.