Section 4.11. Heredoc Terminators

4.11. Heredoc Terminators

Make every heredoc terminator a single uppercase identifier with a standard prefix.

You can use just about anything you like as a heredoc terminator. For example:

     print <<'end list';          # Prints 3 lines then [DONE]     get name     set size     put next     end list     print "[DONE]\n";

or:

     print <<'';                  # Prints 4 lines (up to the empty line) then [DONE]     get name     set size     put next     end list     print "[DONE]\n";

or even:

     print <<'print "[DONE]\n";'; # Prints 5 lines but no [DONE]!     get name     set size     put next     end list     print "[DONE]\n";

Please don't. Heredocs are tough enough to understand as it is. Using bizarre terminators only makes them more difficult. It's a far better practice to stick with terminators that are capitalized (so they stand out better in mixed-case code) and free of whitespace (so only a single visual token has to be recognized).

For example, compared to the previous examples, it's much easier to tell what the contents of the following heredoc are:

      print <<'END_LIST';     get name     set size     put next     END_LIST

But even with a single identifier as terminator, both the contents and the termination marker of a heredoc still have to be left-justified. So it can still be difficult to detect the end of a heredoc. By naming every heredoc marker with a standard, easily recognized prefix, you can make them much easier to pick out.

'END_...' is the recommended choice for this prefix. That is, instead of:

     Readonly my $USAGE => <<"USAGE";     Usage: $0 <file> [-full] [-o] [-beans]     Options:         -full  : produce a full dump         -o     : dump in octal         -beans : source is Java     USAGE

delimit your heredocs like so:

      Readonly my $USAGE => <<"END_USAGE";     Usage: $0 <file> [-full] [-o] [-beans]     Options:         -full  : produce a full dump         -o     : dump in octal         -beans : source is Java     END_USAGE

It helps to think of the << heredoc introducer as being pronounced "Everything up to...", so that the previous code reads as: the read-only $USAGE variable is initialized with everything up to END_USAGE.