Use a "theredoc" when a heredoc would compromise your indentation .
Of course, even if your lines
are all simple strings, the problem with using a heredoc in the middle of code is that its contents must be left-justified, regardless of the indentation level of the code it's in:
if ($usage_error) {
warn <<'END_USAGE';
Usage: qdump <file> [-full] [-o] [-beans]
Options:
-full : produce a full dump
-o : dump in octal
-beans : source is Java
END_USAGE
}A better practice is to factor out any such heredoc into a predefined constant or a subroutine (a "theredoc"):
use Readonly; Readonly my $USAGE => <<'END_USAGE'; Usage: qdump file [-full] [-o] [-beans] Options: -full : produce a full dump -o : dump in octal -beans : source is Java END_USAGE
# and later...if ($usage_error) { warn $USAGE; }
If the heredoc needs to interpolate variables whose values are not known at compile time, use a subroutine instead, and parameterize the variables:
sub build_usage { my ($prog_name, $filename) = @_; return <<"END_USAGE"; Usage: $prog_name $filename [-full] [-o] [-beans] Options: -full : produce a full dump -o : dump in octal -beans : source is Java END_USAGE }
# and later...if ($usage_error) { warn build_usage($PROGRAM_NAME, $requested_file); }
The heredoc does compromise the indentation of the subroutine, but that's now a small and isolated section of the code, so it doesn't significantly impair the overall readability of your program.