perlmeditation
xdg
<p>Recently, as I was writing error messages for various instances of <code>carp</code>, <code>croak</code>, <code>warn</code> and <code>die</code>, I realized that -- unlike with my code -- I've never quite settled into a consistent, personal "style" for phrasing and formatting error messages.
</p>
<p>Some of this, I think, is a result of the error messages being something of an afterthought -- a sort of, <i>"oh, yeah, I should throw an error if that fails"</i> postcript, where once the <code>die</code> statement has hit the screen, I want to get back to coding and the error message winds up being whatever quickly comes to mind.</p>
<p>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 [mod://Devel::Cover] run and filling in test scripts for all the untriggered error handlers.</p>
<p>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:</p>
<ul>
<li><p>Target the error message at the source of the error
<ul>
<li>Use <code>carp</code> and <code>croak</code> for messages about parameters or other user input</li>
<li>Use <code>warn</code> and <code>die</code> for unexpected system behavior or failures that "shouldn't happen"</li>
</ul>
</p></li>
<li><p>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)</p></li>
<li><p>Don't provide the line number if the error came from runtime input (i.e. end the message with "\n")</p></li>
<li><p>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:"</p></li>
<li><p>Start the message with a brief description of the <i>result</i> of the error</p></li>
<li><p>Include the <i>cause</i> of the error by appending <code>$!</code> or <code>$@</code> as appropriate</p></li>
</ul>
<p>If a style guide was in use, a template could be used with <code>throws_ok</code> from [mod://Test::Exception] to ensure some minimal conformity, without necessarily (unless desired) needing to check the entire error string. E.g.:</p>
<code>
throws_ok { some_function() } qr{\AError: .+}, "some_function() error handling";
</code>
<p>What best practices have you found for error messages? Does anyone have a particular style guide within their company or team? Other than [doc://die] mentioning that adding ", stopped" can help readability, I've not seen much by way of concrete recommendations.</p>
<div class="pmsig"><div class="pmsig-268515">
<p>-xdg</p>
<p><small><i>Code written by xdg and posted on PerlMonks is <a href="http://creativecommons.org/licenses/publicdomain">public domain</a>. It is provided <b>as is</b> 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.</i></small></p>
</div></div>