| 1 | =head1 NAME |
| 2 | |
| 3 | perlstyle - Perl style guide |
| 4 | |
| 5 | =head1 DESCRIPTION |
| 6 | |
| 7 | Each programmer will, of course, have his or her own preferences in |
| 8 | regards to formatting, but there are some general guidelines that will |
| 9 | make your programs easier to read, understand, and maintain. |
| 10 | |
| 11 | The most important thing is to run your programs under the B<-w> |
| 12 | flag at all times. You may turn it off explicitly for particular |
| 13 | portions of code via the C<no warnings> pragma or the C<$^W> variable |
| 14 | if you must. You should also always run under C<use strict> or know the |
| 15 | reason why not. The C<use sigtrap> and even C<use diagnostics> pragmas |
| 16 | may also prove useful. |
| 17 | |
| 18 | Regarding aesthetics of code lay out, about the only thing Larry |
| 19 | cares strongly about is that the closing curly bracket of |
| 20 | a multi-line BLOCK should line up with the keyword that started the construct. |
| 21 | Beyond that, he has other preferences that aren't so strong: |
| 22 | |
| 23 | =over 4 |
| 24 | |
| 25 | =item * |
| 26 | |
| 27 | 4-column indent. |
| 28 | |
| 29 | =item * |
| 30 | |
| 31 | Opening curly on same line as keyword, if possible, otherwise line up. |
| 32 | |
| 33 | =item * |
| 34 | |
| 35 | Space before the opening curly of a multi-line BLOCK. |
| 36 | |
| 37 | =item * |
| 38 | |
| 39 | One-line BLOCK may be put on one line, including curlies. |
| 40 | |
| 41 | =item * |
| 42 | |
| 43 | No space before the semicolon. |
| 44 | |
| 45 | =item * |
| 46 | |
| 47 | Semicolon omitted in "short" one-line BLOCK. |
| 48 | |
| 49 | =item * |
| 50 | |
| 51 | Space around most operators. |
| 52 | |
| 53 | =item * |
| 54 | |
| 55 | Space around a "complex" subscript (inside brackets). |
| 56 | |
| 57 | =item * |
| 58 | |
| 59 | Blank lines between chunks that do different things. |
| 60 | |
| 61 | =item * |
| 62 | |
| 63 | Uncuddled elses. |
| 64 | |
| 65 | =item * |
| 66 | |
| 67 | No space between function name and its opening parenthesis. |
| 68 | |
| 69 | =item * |
| 70 | |
| 71 | Space after each comma. |
| 72 | |
| 73 | =item * |
| 74 | |
| 75 | Long lines broken after an operator (except C<and> and C<or>). |
| 76 | |
| 77 | =item * |
| 78 | |
| 79 | Space after last parenthesis matching on current line. |
| 80 | |
| 81 | =item * |
| 82 | |
| 83 | Line up corresponding items vertically. |
| 84 | |
| 85 | =item * |
| 86 | |
| 87 | Omit redundant punctuation as long as clarity doesn't suffer. |
| 88 | |
| 89 | =back |
| 90 | |
| 91 | Larry has his reasons for each of these things, but he doesn't claim that |
| 92 | everyone else's mind works the same as his does. |
| 93 | |
| 94 | Here are some other more substantive style issues to think about: |
| 95 | |
| 96 | =over 4 |
| 97 | |
| 98 | =item * |
| 99 | |
| 100 | Just because you I<CAN> do something a particular way doesn't mean that |
| 101 | you I<SHOULD> do it that way. Perl is designed to give you several |
| 102 | ways to do anything, so consider picking the most readable one. For |
| 103 | instance |
| 104 | |
| 105 | open(FOO,$foo) || die "Can't open $foo: $!"; |
| 106 | |
| 107 | is better than |
| 108 | |
| 109 | die "Can't open $foo: $!" unless open(FOO,$foo); |
| 110 | |
| 111 | because the second way hides the main point of the statement in a |
| 112 | modifier. On the other hand |
| 113 | |
| 114 | print "Starting analysis\n" if $verbose; |
| 115 | |
| 116 | is better than |
| 117 | |
| 118 | $verbose && print "Starting analysis\n"; |
| 119 | |
| 120 | because the main point isn't whether the user typed B<-v> or not. |
| 121 | |
| 122 | Similarly, just because an operator lets you assume default arguments |
| 123 | doesn't mean that you have to make use of the defaults. The defaults |
| 124 | are there for lazy systems programmers writing one-shot programs. If |
| 125 | you want your program to be readable, consider supplying the argument. |
| 126 | |
| 127 | Along the same lines, just because you I<CAN> omit parentheses in many |
| 128 | places doesn't mean that you ought to: |
| 129 | |
| 130 | return print reverse sort num values %array; |
| 131 | return print(reverse(sort num (values(%array)))); |
| 132 | |
| 133 | When in doubt, parenthesize. At the very least it will let some poor |
| 134 | schmuck bounce on the % key in B<vi>. |
| 135 | |
| 136 | Even if you aren't in doubt, consider the mental welfare of the person |
| 137 | who has to maintain the code after you, and who will probably put |
| 138 | parentheses in the wrong place. |
| 139 | |
| 140 | =item * |
| 141 | |
| 142 | Don't go through silly contortions to exit a loop at the top or the |
| 143 | bottom, when Perl provides the C<last> operator so you can exit in |
| 144 | the middle. Just "outdent" it a little to make it more visible: |
| 145 | |
| 146 | LINE: |
| 147 | for (;;) { |
| 148 | statements; |
| 149 | last LINE if $foo; |
| 150 | next LINE if /^#/; |
| 151 | statements; |
| 152 | } |
| 153 | |
| 154 | =item * |
| 155 | |
| 156 | Don't be afraid to use loop labels--they're there to enhance |
| 157 | readability as well as to allow multilevel loop breaks. See the |
| 158 | previous example. |
| 159 | |
| 160 | =item * |
| 161 | |
| 162 | Avoid using C<grep()> (or C<map()>) or `backticks` in a void context, that is, |
| 163 | when you just throw away their return values. Those functions all |
| 164 | have return values, so use them. Otherwise use a C<foreach()> loop or |
| 165 | the C<system()> function instead. |
| 166 | |
| 167 | =item * |
| 168 | |
| 169 | For portability, when using features that may not be implemented on |
| 170 | every machine, test the construct in an eval to see if it fails. If |
| 171 | you know what version or patchlevel a particular feature was |
| 172 | implemented, you can test C<$]> (C<$PERL_VERSION> in C<English>) to see if it |
| 173 | will be there. The C<Config> module will also let you interrogate values |
| 174 | determined by the B<Configure> program when Perl was installed. |
| 175 | |
| 176 | =item * |
| 177 | |
| 178 | Choose mnemonic identifiers. If you can't remember what mnemonic means, |
| 179 | you've got a problem. |
| 180 | |
| 181 | =item * |
| 182 | |
| 183 | While short identifiers like C<$gotit> are probably ok, use underscores to |
| 184 | separate words in longer identifiers. It is generally easier to read |
| 185 | C<$var_names_like_this> than C<$VarNamesLikeThis>, especially for |
| 186 | non-native speakers of English. It's also a simple rule that works |
| 187 | consistently with C<VAR_NAMES_LIKE_THIS>. |
| 188 | |
| 189 | Package names are sometimes an exception to this rule. Perl informally |
| 190 | reserves lowercase module names for "pragma" modules like C<integer> and |
| 191 | C<strict>. Other modules should begin with a capital letter and use mixed |
| 192 | case, but probably without underscores due to limitations in primitive |
| 193 | file systems' representations of module names as files that must fit into a |
| 194 | few sparse bytes. |
| 195 | |
| 196 | =item * |
| 197 | |
| 198 | You may find it helpful to use letter case to indicate the scope |
| 199 | or nature of a variable. For example: |
| 200 | |
| 201 | $ALL_CAPS_HERE constants only (beware clashes with perl vars!) |
| 202 | $Some_Caps_Here package-wide global/static |
| 203 | $no_caps_here function scope my() or local() variables |
| 204 | |
| 205 | Function and method names seem to work best as all lowercase. |
| 206 | E.g., C<$obj-E<gt>as_string()>. |
| 207 | |
| 208 | You can use a leading underscore to indicate that a variable or |
| 209 | function should not be used outside the package that defined it. |
| 210 | |
| 211 | =item * |
| 212 | |
| 213 | If you have a really hairy regular expression, use the C</x> modifier and |
| 214 | put in some whitespace to make it look a little less like line noise. |
| 215 | Don't use slash as a delimiter when your regexp has slashes or backslashes. |
| 216 | |
| 217 | =item * |
| 218 | |
| 219 | Use the new C<and> and C<or> operators to avoid having to parenthesize |
| 220 | list operators so much, and to reduce the incidence of punctuation |
| 221 | operators like C<&&> and C<||>. Call your subroutines as if they were |
| 222 | functions or list operators to avoid excessive ampersands and parentheses. |
| 223 | |
| 224 | =item * |
| 225 | |
| 226 | Use here documents instead of repeated C<print()> statements. |
| 227 | |
| 228 | =item * |
| 229 | |
| 230 | Line up corresponding things vertically, especially if it'd be too long |
| 231 | to fit on one line anyway. |
| 232 | |
| 233 | $IDX = $ST_MTIME; |
| 234 | $IDX = $ST_ATIME if $opt_u; |
| 235 | $IDX = $ST_CTIME if $opt_c; |
| 236 | $IDX = $ST_SIZE if $opt_s; |
| 237 | |
| 238 | mkdir $tmpdir, 0700 or die "can't mkdir $tmpdir: $!"; |
| 239 | chdir($tmpdir) or die "can't chdir $tmpdir: $!"; |
| 240 | mkdir 'tmp', 0777 or die "can't mkdir $tmpdir/tmp: $!"; |
| 241 | |
| 242 | =item * |
| 243 | |
| 244 | Always check the return codes of system calls. Good error messages should |
| 245 | go to C<STDERR>, include which program caused the problem, what the failed |
| 246 | system call and arguments were, and (VERY IMPORTANT) should contain the |
| 247 | standard system error message for what went wrong. Here's a simple but |
| 248 | sufficient example: |
| 249 | |
| 250 | opendir(D, $dir) or die "can't opendir $dir: $!"; |
| 251 | |
| 252 | =item * |
| 253 | |
| 254 | Line up your transliterations when it makes sense: |
| 255 | |
| 256 | tr [abc] |
| 257 | [xyz]; |
| 258 | |
| 259 | =item * |
| 260 | |
| 261 | Think about reusability. Why waste brainpower on a one-shot when you |
| 262 | might want to do something like it again? Consider generalizing your |
| 263 | code. Consider writing a module or object class. Consider making your |
| 264 | code run cleanly with C<use strict> and C<use warnings> (or B<-w>) in |
| 265 | effect. Consider giving away your code. Consider changing your whole |
| 266 | world view. Consider... oh, never mind. |
| 267 | |
| 268 | =item * |
| 269 | |
| 270 | Try to document your code and use Pod formatting in a consistent way. Here |
| 271 | are commonly expected conventions: |
| 272 | |
| 273 | =over 4 |
| 274 | |
| 275 | =item * |
| 276 | |
| 277 | use C<CE<lt>E<gt>> for function, variable and module names (and more |
| 278 | generally anything that can be considered part of code, like filehandles |
| 279 | or specific values). Note that function names are considered more readable |
| 280 | with parentheses after their name, that is C<function()>. |
| 281 | |
| 282 | =item * |
| 283 | |
| 284 | use C<BE<lt>E<gt>> for commands names like B<cat> or B<grep>. |
| 285 | |
| 286 | =item * |
| 287 | |
| 288 | use C<FE<lt>E<gt>> or C<CE<lt>E<gt>> for file names. C<FE<lt>E<gt>> should |
| 289 | be the only Pod code for file names, but as most Pod formatters render it |
| 290 | as italic, Unix and Windows paths with their slashes and backslashes may |
| 291 | be less readable, and better rendered with C<CE<lt>E<gt>>. |
| 292 | |
| 293 | =back |
| 294 | |
| 295 | =item * |
| 296 | |
| 297 | Be consistent. |
| 298 | |
| 299 | =item * |
| 300 | |
| 301 | Be nice. |
| 302 | |
| 303 | =back |