pod/perlstyle.pod

   1 =head1 NAME
   2
   3 perlstyle - Perl style guide
   4
   5 =head1 DESCRIPTION
   6
   7 =head2 Style
   8
   9 Each programmer will, of course, have his or her own preferences in
  10 regards to formatting, but there are some general guidelines that will
  11 make your programs easier to read, understand, and maintain.
  12
  13 Regarding aesthetics of code lay out, about the only thing Larry
  14 cares strongly about is that the closing curly brace of
  15 a multi-line BLOCK should line up with the keyword that started the construct.
  16 Beyond that, he has other preferences that aren't so strong:
  17
  18 =over 4
  19
  20 =item *
  21
  22 4-column indent.
  23
  24 =item *
  25
  26 Opening curly on same line as keyword, if possible, otherwise line up.
  27
  28 =item *
  29
  30 Space before the opening curly of a multiline BLOCK.
  31
  32 =item *
  33
  34 One-line BLOCK may be put on one line, including curlies.
  35
  36 =item *
  37
  38 No space before the semicolon.
  39
  40 =item *
  41
  42 Semicolon omitted in "short" one-line BLOCK.
  43
  44 =item *
  45
  46 Space around most operators.
  47
  48 =item *
  49
  50 Space around a "complex" subscript (inside brackets).
  51
  52 =item *
  53
  54 Blank lines between chunks that do different things.
  55
  56 =item *
  57
  58 Uncuddled elses.
  59
  60 =item *
  61
  62 No space between function name and its opening paren.
  63
  64 =item *
  65
  66 Space after each comma.
  67
  68 =item *
  69
  70 Long lines broken after an operator (except "and" and "or").
  71
  72 =item *
  73
  74 Space after last paren matching on current line.
  75
  76 =item *
  77
  78 Line up corresponding items vertically.
  79
  80 =item *
  81
  82 Omit redundant punctuation as long as clarity doesn't suffer.
  83
  84 =back
  85
  86 Larry has his reasons for each of these things, but he doen't claim that
  87 everyone else's mind works the same as his does.
  88
  89 Here are some other more substantive style issues to think about:
  90
  91 =over 4
  92
  93 =item *
  94
  95 Just because you I<CAN> do something a particular way doesn't mean that
  96 you I<SHOULD> do it that way.  Perl is designed to give you several
  97 ways to do anything, so consider picking the most readable one.  For
  98 instance
  99
 100     open(FOO,$foo) || die "Can't open $foo: $!";
 101
 102 is better than
 103
 104     die "Can't open $foo: $!" unless open(FOO,$foo);
 105
 106 because the second way hides the main point of the statement in a
 107 modifier.  On the other hand
 108
 109     print "Starting analysis\n" if $verbose;
 110
 111 is better than
 112
 113     $verbose && print "Starting analysis\n";
 114
 115 since the main point isn't whether the user typed B<-v> or not.
 116
 117 Similarly, just because an operator lets you assume default arguments
 118 doesn't mean that you have to make use of the defaults.  The defaults
 119 are there for lazy systems programmers writing one-shot programs.  If
 120 you want your program to be readable, consider supplying the argument.
 121
 122 Along the same lines, just because you I<CAN> omit parentheses in many
 123 places doesn't mean that you ought to:
 124
 125     return print reverse sort num values %array;
 126     return print(reverse(sort num (values(%array))));
 127
 128 When in doubt, parenthesize.  At the very least it will let some poor
 129 schmuck bounce on the % key in B<vi>.
 130
 131 Even if you aren't in doubt, consider the mental welfare of the person
 132 who has to maintain the code after you, and who will probably put
 133 parens in the wrong place.
 134
 135 =item *
 136
 137 Don't go through silly contortions to exit a loop at the top or the
 138 bottom, when Perl provides the C<last> operator so you can exit in
 139 the middle.  Just "outdent" it a little to make it more visible:
 140
 141     LINE:
 142         for (;;) {
 143             statements;
 144           last LINE if $foo;
 145             next LINE if /^#/;
 146             statements;
 147         }
 148
 149 =item *
 150
 151 Don't be afraid to use loop labels--they're there to enhance
 152 readability as well as to allow multi-level loop breaks.  See the
 153 previous example.
 154
 155 =item *
 156
 157 For portability, when using features that may not be implemented on
 158 every machine, test the construct in an eval to see if it fails.  If
 159 you know what version or patchlevel a particular feature was
 160 implemented, you can test C<$]> ($PERL_VERSION in C<English>) to see if it
 161 will be there.  The C<Config> module will also let you interrogate values
 162 determined by the B<Configure> program when Perl was installed.
 163
 164 =item *
 165
 166 Choose mnemonic identifiers.  If you can't remember what mnemonic means,
 167 you've got a problem.
 168
 169 =item *
 170
 171 If you have a really hairy regular expression, use the C</x> modifier and
 172 put in some whitespace to make it look a little less like line noise.
 173 Don't use slash as a delimiter when your regexp has slashes or backslashes.
 174
 175 =item *
 176
 177 Use the new "and" and "or" operators to avoid having to parenthesize
 178 list operators so much, and to reduce the incidence of punctuational
 179 operators like C<&&> and C<||>.  Call your subroutines as if they were
 180 functions or list operators to avoid excessive ampersands and parens.
 181
 182 =item *
 183
 184 Use here documents instead of repeated print() statements.
 185
 186 =item *
 187
 188 Line up corresponding things vertically, especially if it'd be too long
 189 to fit on one line anyway.
 190
 191     $IDX = $ST_MTIME;
 192     $IDX = $ST_ATIME       if $opt_u;
 193     $IDX = $ST_CTIME       if $opt_c;
 194     $IDX = $ST_SIZE        if $opt_s;
 195
 196     mkdir $tmpdir, 0700 or die "can't mkdir $tmpdir: $!";
 197     chdir($tmpdir)      or die "can't chdir $tmpdir: $!";
 198     mkdir 'tmp',   0777 or die "can't mkdir $tmpdir/tmp: $!";
 199
 200 =item *
 201
 202 Line up your translations when it makes sense:
 203
 204     tr [abc]
 205        [xyz];
 206
 207 =item *
 208
 209 Think about reusability.  Why waste brainpower on a one-shot when you
 210 might want to do something like it again?  Consider generalizing your
 211 code.  Consider writing a module or object class.  Consider making your
 212 code run cleanly with C<use strict> and B<-w> in effect.  Consider giving away
 213 your code.  Consider changing your whole world view.  Consider... oh,
 214 never mind.
 215
 216 =item *
 217
 218 Be consistent.
 219
 220 =item *
 221
 222 Be nice.
 223
 224 =back
 225