Section 13.8. Documenting Errors

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     =over     =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.