Section 7.10.  Elucidating Documentation

7.10. Elucidating Documentation

Use end-of-line comments to point out subtleties and oddities.

The guidelines in this book aim to help you write code that's self-documenting, so most lines within a single paragraph shouldn't require extra "hints" in order to understand them.

But self-documentation is always in the eye of the original author, and code that seemed perfectly clear when it was written may be somewhat less intelligible when it's re-read six months later.

Comprehensibility can suffer particularly badly when the code incorporates jargon from the problem domain. Terms that were extremely familiar to the original designers and implementers might mean nothing to those who later have to maintain the source. For example, you could inherit code like this:

    my $QFETM_func_ref;

    if ($QFETM_func_ref  = get_GET(  )) {
        make_futtock($QFETM_func_ref);
    }

    $build_mode = oct $arg{mode};

in which case, the judicious application of trailing comments is appropriate:

    my $QFETM_func_ref;  
# stores Quantum Field Effect Transfer Mode function

    # Build futtock representation if remote data is available...
    if ($QFETM_func_ref  = get_GET(  )) {    
# instead of get_POST(  )
        make_futtock($QFETM_func_ref);     
# futtock: a rib of a ship's frame
    }

    $build_mode = oct $arg{mode};   
# *From* octal, not *to* octal

End-of-line comments should be kept pithy. If you feel that an elucidating comment needs more than the remainder of the current line, then use a discursive comment instead (see "Discursive Documentation" later in this chapter).