Beefy Boxes and Bandwidth Generously Provided by pair Networks
We don't bite newbies here... much

comment on

( #3333=superdoc: print w/replies, xml ) Need Help??

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";

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.


Code written by xdg and posted on PerlMonks is public domain. It is provided as is with no warranties, express or implied, of any kind. Posted code may not have been tested. Use of posted code is at your own risk.

In reply to Style guide for error messages? by xdg

Use:  <p> text here (a paragraph) </p>
and:  <code> code here </code>
to format your post; it's "PerlMonks-approved HTML":

  • Are you posting in the right place? Check out Where do I post X? to know for sure.
  • Posts may use any of the Perl Monks Approved HTML tags. Currently these include the following:
    <code> <a> <b> <big> <blockquote> <br /> <dd> <dl> <dt> <em> <font> <h1> <h2> <h3> <h4> <h5> <h6> <hr /> <i> <li> <nbsp> <ol> <p> <small> <strike> <strong> <sub> <sup> <table> <td> <th> <tr> <tt> <u> <ul>
  • Snippets of code should be wrapped in <code> tags not <pre> tags. In fact, <pre> tags should generally be avoided. If they must be used, extreme care should be taken to ensure that their contents do not have long lines (<70 chars), in order to prevent horizontal scrolling (and possible janitor intervention).
  • Want more info? How to link or How to display code and escape characters are good places to start.
Log In?

What's my password?
Create A New User
Domain Nodelet?
and the web crawler heard nothing...

How do I use this? | Other CB clients
Other Users?
Others chanting in the Monastery: (2)
As of 2023-02-05 08:14 GMT
Find Nodes?
    Voting Booth?
    I prefer not to run the latest version of Perl because:

    Results (31 votes). Check out past polls.