Section 13.8.  Documenting Errors

Table of Contents

13.8. Documenting Errors

Document every error message in the recipient's dialect.

It's important to document every exception (or warning) your code may ever generate (see Chapter 7), but it's vital to do so in a way that will be comprehensible to the likely recipient of these messages.

For example, suppose someone uses your new Random::Utils module:

    use Random::Utils qw( pick_from );

# and later...
$random_item = pick_from(@items);

And suppose that call to pick_from( ) causes their program to terminate unexpectedly with the message:

    Can't pick a random element from an empty list at monte_carlo.pl line 42

If they're not familiar with your module, they may be unsure what the problem is, or what caused it, or what to do about it. In which case, you'd hope that they'll try and work out what to do by reading the fine Random::Utils manual[*].

[*] Rather than, say, sending you the usual mail message entitled "YOUR RANDOM LIBRARY IS B0RKEN!!!!", that consists of a single sentence "Please fix this Perl bug *ASAP*", followed by a 20MB file attachment (problem.gz.tar.zip.uu.Z) containing a recentthough not currentversion of their entire source tree.

That kind of self-help will be far more likely to happen if your documentation actually does help readers solve their problems. To achieve that goal, you first need to explain the problem more fully, in one or more complete sentences; sentences that are longerand written in less dense languagethan the error message itself. You should then describe the most common causes of the problem, and finally suggest how the offending code might be fixed. For example:

    =head1 DIAGNOSTICS

    =item Can't pick an element from an empty list

    The C<pick_from(  )> subroutine was called without any arguments, which
    meant it had no values to choose amongst. Perhaps you forgot to supply
    an argument to C<pick_from(  )>. Alternatively, maybe you passed an
    array to the subroutine, but that array was empty at the time.
    If you need to pass C<pick_from(  )> an array that might sometimes have no
    elements, try using the C<pick_with_default_from(  )>  subroutine instead
    (see L<Picking randomly with a fall-back value>).

The standard perldiag documentation is a superb example of this user-friendly approach to documenting exceptions and warnings. For example, it explains the mysteriously Zen-like Attempt to join self error message like so:

    =item Attempt to join self

    (F) You tried to join a thread from within itself, which is an
    impossible task.  You may be joining the wrong thread, or you may
    need to move the C<join(  )> to some other thread.

    Table of Contents
    © 2000- NIV