Section 7.13.  Discursive Documentation

Table of Contents

7.13. Discursive Documentation

Use "invisible" POD sections for longer technical discussions.

The =for and =begin/=end POD directives provide an easy way to create large blocks of text that are ignored by the compiler and don't produce any visible output when the surrounding file is processed by a POD formatter. So these directives provide an easy way to embed extended pieces of internal documentation within your source.

The =for directive is identical to a =begin/=end pair, except that it allows only a single paragraph of content, terminated by an empty line. This might well be construed as a feature, in that it encourages conciseness[*]. But note that you still have to provide a trailing =cut, to switch the compiler back from skipping documentation to compiling Perl code.

[*] The only thing harder than finally convincing coders to write comments is then convincing them to write short comments.

Both these forms of block commenting take a "format name" after the keyword. Normally this name would be used to indicate which formatting tool the documentation is intended for (e.g., =for html ..., =for groff ..., =for LaTeX ...), but it is far more useful as a means to specify the kind of internal documentation you are writing. Then, provided the description you choose doesn't match the name of one of the standard POD formatters, the resulting POD block will be effectively invisible outside the source code. An easy way to ensure that invisibility is to capitalize the description and put a colon at the end of it.

For example, you can use this approach to record your rationale for unusual design or implementation decisions:

    =for Rationale:
         We chose arrays over hashes here because profiling indicated over
         99% of accesses were iterated over the entire set, rather than being
         random. The dataset is expected to grow big enough that the better
         access performance and smaller memory footprint of a big array will
         outweigh the awkwardness of the occasional binary-chop search.


You can make notes on possible improvements that you don't currently have time to design or implement:

    =for Improvement:
         Would be handier if this subroutine also accepted UMT values


Or explain any obscure pieces of domain-specific information that necessitated unusual implementation approaches:

    =for Domain:
         No observation is ever recorded without an error bound. Hence the
         use of interval arithmetic in the next three subroutines.


Or mark sections that might benefit from optimization or that ought to be rewritten, making note of the conditions under which that might be possible:

    =for Optimization:
         This parser would almost certainly benefit from the use of
         progressive matching with m/\G.../gcxms, rather than relying
         on successive prefix substitutions.
         Reconsider when everyone is using at least Perl 5.6.1.


Or highlight workarounds necessitated by limitations in Perl itself (or perl itself):

    =for Workaround:
         Have to use a localized package variable here, rather than a
         lexical. A closure would be better of course, but lexicals don't seem
         to propagate properly into regexes under 5.8.3 (or earlier). This
         problem has been reported via perlbug.


Avoid the =begin/=end form unless the annotation is large and requires multiple paragraphs or embedded code examples:

    =begin Optimization:

         This parser would almost certainly benefit from the use of
         progressive matching with m/\G.../gcxms, as in:

            while (pos $text < length $text) {
                if (m/\G ($TYPENAME)/gcxms) {
                    push @tokens, Token::Type->new({ name => $1 });
                elsif (m/\G ($VARNAME)/gcxms) {
                    push @tokens, Token::Var->new({ alias => $1 });
                # etc.
                else {
                    croak q{Don't understand '},
                          substr($text, pos $text, 20),

         Reconsider when everyone is using at least Perl 5.6.1.

    =end Optimization


Note that, unlike the consolidated "visible" POD written for user documentation, the "invisible" POD containing these technical discussions should be kept as close as possible to the code it refers to. Furthermore, since this documentation is "for internal use only" and never intended for any POD formatter, don't use POD mark-up within these sections.

    Table of Contents
    © 2000- NIV