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