extra code in pp_concat, Take 2
[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
0c506aae 13portions of code via the C<no warnings> pragma or the C<$^W> variable
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
75Long lines broken after an operator (except "and" and "or").
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
c07a80fd 162Avoid using grep() (or map()) or `backticks` in a void context, that is,
54310121 163when you just throw away their return values. Those functions all
c07a80fd 164have return values, so use them. Otherwise use a foreach() loop or
165the system() function instead.
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
183While short identifiers like $gotit are probably ok, use underscores to
184separate words. It is generally easier to read $var_names_like_this than
185$VarNamesLikeThis, especially for non-native speakers of English. It's
186also a simple rule that works consistently with VAR_NAMES_LIKE_THIS.
187
188Package names are sometimes an exception to this rule. Perl informally
189reserves lowercase module names for "pragma" modules like C<integer> and
190C<strict>. Other modules should begin with a capital letter and use mixed
191case, but probably without underscores due to limitations in primitive
5f05dabc 192file systems' representations of module names as files that must fit into a
54310121 193few sparse bytes.
cb1a09d0 194
195=item *
196
54310121 197You may find it helpful to use letter case to indicate the scope
198or nature of a variable. For example:
cb1a09d0 199
54310121 200 $ALL_CAPS_HERE constants only (beware clashes with perl vars!)
201 $Some_Caps_Here package-wide global/static
202 $no_caps_here function scope my() or local() variables
cb1a09d0 203
54310121 204Function and method names seem to work best as all lowercase.
205E.g., $obj-E<gt>as_string().
cb1a09d0 206
207You can use a leading underscore to indicate that a variable or
208function should not be used outside the package that defined it.
209
a0d0e21e 210=item *
211
212If you have a really hairy regular expression, use the C</x> modifier and
213put in some whitespace to make it look a little less like line noise.
214Don't use slash as a delimiter when your regexp has slashes or backslashes.
215
216=item *
217
218Use the new "and" and "or" operators to avoid having to parenthesize
5f05dabc 219list operators so much, and to reduce the incidence of punctuation
a0d0e21e 220operators like C<&&> and C<||>. Call your subroutines as if they were
5f05dabc 221functions or list operators to avoid excessive ampersands and parentheses.
a0d0e21e 222
223=item *
224
225Use here documents instead of repeated print() statements.
226
227=item *
228
229Line up corresponding things vertically, especially if it'd be too long
54310121 230to fit on one line anyway.
a0d0e21e 231
54310121 232 $IDX = $ST_MTIME;
233 $IDX = $ST_ATIME if $opt_u;
234 $IDX = $ST_CTIME if $opt_c;
235 $IDX = $ST_SIZE if $opt_s;
a0d0e21e 236
237 mkdir $tmpdir, 0700 or die "can't mkdir $tmpdir: $!";
238 chdir($tmpdir) or die "can't chdir $tmpdir: $!";
239 mkdir 'tmp', 0777 or die "can't mkdir $tmpdir/tmp: $!";
240
241=item *
242
cb1a09d0 243Always check the return codes of system calls. Good error messages should
244go to STDERR, include which program caused the problem, what the failed
7b8d334a 245system call and arguments were, and (VERY IMPORTANT) should contain the
cb1a09d0 246standard system error message for what went wrong. Here's a simple but
247sufficient example:
248
249 opendir(D, $dir) or die "can't opendir $dir: $!";
250
251=item *
252
2c268ad5 253Line up your transliterations when it makes sense:
a0d0e21e 254
255 tr [abc]
256 [xyz];
257
258=item *
259
260Think about reusability. Why waste brainpower on a one-shot when you
261might want to do something like it again? Consider generalizing your
262code. Consider writing a module or object class. Consider making your
0c506aae 263code run cleanly with C<use strict> and C<use warnings> (or B<-w>) in
264effect. Consider giving away your code. Consider changing your whole
265world view. Consider... oh, never mind.
a0d0e21e 266
267=item *
268
269Be consistent.
270
271=item *
272
273Be nice.
274
275=back