2.13. Chunking

Code in paragraphs.

A paragraph is a collection of statements that accomplish a single task: in literature, it's a series of sentences conveying a single idea; in programming, it's a series of instructions implementing a single step of an algorithm.

Break each piece of code into sequences that achieve a single task, placing a single empty line between each sequence. To further improve the maintainability of the code, place a one-line comment at the start of each such paragraph, describing what the sequence of statements does. Like so:

    
# Process an array that has been recognized...
    sub addarray_internal {
        my ($var_name, $needs_quotemeta) = @_;

        
# Cache the original...
        $raw .= $var_name;

        
# Build meta-quoting code, if requested...
        my $quotemeta = $needs_quotemeta ?  q{map {quotemeta $_} } : $EMPTY_STR;

        
# Expand elements of variable, conjoin with ORs...
        my $perl5pat = qq{(??{join q{|}, $quotemeta \@{$var_name}})};

        
# Insert debugging code if requested...
        my $type = $quotemeta ? 'literal' : 'pattern';
        debug_now("Adding $var_name (as $type)");
        add_debug_mesg("Trying $var_name (as $type)");

        return $perl5pat;
    }

Paragraphs are useful because humans can focus on only a few pieces of information at once^[*]. Paragraphs are one way of aggregating small amounts of related information, so that the resulting "chunk" can fit into a single slot of the reader's limited short-term memory. Paragraphs enable the physical structure of a piece of writing to reflect and emphasize its logical structure. Adding comments at the start of each paragraph further enhances the chunking by explicitly summarizing the purpose^[] of each chunk.

^[*] An idea made famous in 1956 by George A. Miller in "The Magical Number Seven, Plus or Minus Two" (The Psychological Review, 1956, Vol. 63, pp. 81-97).

^[] The purpose, not the actions. Paragraph comments need to explain why the code is needed, not merely paraphrase what it's doing.

Note, however, that the contents of paragraphs are only of secondary importance here. It is the vertical gaps separating each paragraph that are critical. Without them, the readability of the code declines dramatically, even if the comments are retained:

    sub addarray_internal {
        my ($var_name, $needs_quotemeta) = @_;
        # Cache the original...
        $raw .= $var_name;
    # Build meta-quoting code, if required...
        my $quotemeta = $needs_quotemeta ?  q{map {quotemeta $_} } : $EMPTY_STR;
        # Expand elements of variable, conjoin with ORs...
        my $perl5pat = qq{(??{join q{|}, $quotemeta \@{$var_name}})};
    # Insert debugging code if requested...
        my $type = $quotemeta ? 'literal' : 'pattern';
        debug_now("Adding $var_name (as $type)");
        add_debug_mesg("Trying $var_name (as $type)");
        return $perl5pat;
    }