Commit | Line | Data |
---|---|---|
a0d0e21e LW |
1 | =head1 NAME |
2 | ||
3 | perlstyle - Perl style guide | |
4 | ||
5 | =head1 DESCRIPTION | |
6 | ||
a0d0e21e LW |
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 | |
54310121 | 9 | make your programs easier to read, understand, and maintain. |
a0d0e21e | 10 | |
cb1a09d0 AD |
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 | |
9f1b1f2d GS |
13 | portions of code via the C<use warnings> pragma or the C<$^W> variable |
14 | if you must. You should | |
cb1a09d0 | 15 | also always run under C<use strict> or know the reason why not. |
184e9718 | 16 | The C<use sigtrap> and even C<use diagnostics> pragmas may also prove |
cb1a09d0 AD |
17 | useful. |
18 | ||
a0d0e21e | 19 | Regarding aesthetics of code lay out, about the only thing Larry |
d98d5fff | 20 | cares strongly about is that the closing curly bracket of |
4a6725af | 21 | a multi-line BLOCK should line up with the keyword that started the construct. |
a0d0e21e LW |
22 | Beyond that, he has other preferences that aren't so strong: |
23 | ||
24 | =over 4 | |
25 | ||
26 | =item * | |
27 | ||
28 | 4-column indent. | |
29 | ||
30 | =item * | |
31 | ||
32 | Opening curly on same line as keyword, if possible, otherwise line up. | |
33 | ||
34 | =item * | |
35 | ||
4a6725af | 36 | Space before the opening curly of a multi-line BLOCK. |
a0d0e21e LW |
37 | |
38 | =item * | |
39 | ||
40 | One-line BLOCK may be put on one line, including curlies. | |
41 | ||
42 | =item * | |
43 | ||
44 | No space before the semicolon. | |
45 | ||
46 | =item * | |
47 | ||
48 | Semicolon omitted in "short" one-line BLOCK. | |
49 | ||
50 | =item * | |
51 | ||
52 | Space around most operators. | |
53 | ||
54 | =item * | |
55 | ||
56 | Space around a "complex" subscript (inside brackets). | |
57 | ||
58 | =item * | |
59 | ||
60 | Blank lines between chunks that do different things. | |
61 | ||
62 | =item * | |
63 | ||
64 | Uncuddled elses. | |
65 | ||
66 | =item * | |
67 | ||
5f05dabc | 68 | No space between function name and its opening parenthesis. |
a0d0e21e LW |
69 | |
70 | =item * | |
71 | ||
72 | Space after each comma. | |
73 | ||
74 | =item * | |
75 | ||
76 | Long lines broken after an operator (except "and" and "or"). | |
77 | ||
78 | =item * | |
79 | ||
5f05dabc | 80 | Space after last parenthesis matching on current line. |
a0d0e21e LW |
81 | |
82 | =item * | |
83 | ||
84 | Line up corresponding items vertically. | |
85 | ||
86 | =item * | |
87 | ||
88 | Omit redundant punctuation as long as clarity doesn't suffer. | |
89 | ||
90 | =back | |
91 | ||
184e9718 | 92 | Larry has his reasons for each of these things, but he doesn't claim that |
a0d0e21e LW |
93 | everyone else's mind works the same as his does. |
94 | ||
95 | Here are some other more substantive style issues to think about: | |
96 | ||
97 | =over 4 | |
98 | ||
99 | =item * | |
100 | ||
101 | Just because you I<CAN> do something a particular way doesn't mean that | |
102 | you I<SHOULD> do it that way. Perl is designed to give you several | |
103 | ways to do anything, so consider picking the most readable one. For | |
104 | instance | |
105 | ||
106 | open(FOO,$foo) || die "Can't open $foo: $!"; | |
107 | ||
108 | is better than | |
109 | ||
110 | die "Can't open $foo: $!" unless open(FOO,$foo); | |
111 | ||
112 | because the second way hides the main point of the statement in a | |
113 | modifier. On the other hand | |
114 | ||
115 | print "Starting analysis\n" if $verbose; | |
116 | ||
117 | is better than | |
118 | ||
119 | $verbose && print "Starting analysis\n"; | |
120 | ||
5f05dabc | 121 | because the main point isn't whether the user typed B<-v> or not. |
a0d0e21e LW |
122 | |
123 | Similarly, just because an operator lets you assume default arguments | |
124 | doesn't mean that you have to make use of the defaults. The defaults | |
125 | are there for lazy systems programmers writing one-shot programs. If | |
126 | you want your program to be readable, consider supplying the argument. | |
127 | ||
128 | Along the same lines, just because you I<CAN> omit parentheses in many | |
129 | places doesn't mean that you ought to: | |
130 | ||
131 | return print reverse sort num values %array; | |
132 | return print(reverse(sort num (values(%array)))); | |
133 | ||
134 | When in doubt, parenthesize. At the very least it will let some poor | |
135 | schmuck bounce on the % key in B<vi>. | |
136 | ||
137 | Even if you aren't in doubt, consider the mental welfare of the person | |
138 | who has to maintain the code after you, and who will probably put | |
5f05dabc | 139 | parentheses in the wrong place. |
a0d0e21e LW |
140 | |
141 | =item * | |
142 | ||
143 | Don't go through silly contortions to exit a loop at the top or the | |
144 | bottom, when Perl provides the C<last> operator so you can exit in | |
145 | the middle. Just "outdent" it a little to make it more visible: | |
146 | ||
147 | LINE: | |
148 | for (;;) { | |
149 | statements; | |
150 | last LINE if $foo; | |
151 | next LINE if /^#/; | |
152 | statements; | |
153 | } | |
154 | ||
155 | =item * | |
156 | ||
157 | Don't be afraid to use loop labels--they're there to enhance | |
54310121 | 158 | readability as well as to allow multilevel loop breaks. See the |
a0d0e21e LW |
159 | previous example. |
160 | ||
161 | =item * | |
162 | ||
c07a80fd | 163 | Avoid using grep() (or map()) or `backticks` in a void context, that is, |
54310121 | 164 | when you just throw away their return values. Those functions all |
c07a80fd | 165 | have return values, so use them. Otherwise use a foreach() loop or |
166 | the system() function instead. | |
167 | ||
168 | =item * | |
169 | ||
a0d0e21e LW |
170 | For portability, when using features that may not be implemented on |
171 | every machine, test the construct in an eval to see if it fails. If | |
172 | you know what version or patchlevel a particular feature was | |
184e9718 | 173 | implemented, you can test C<$]> (C<$PERL_VERSION> in C<English>) to see if it |
a0d0e21e LW |
174 | will be there. The C<Config> module will also let you interrogate values |
175 | determined by the B<Configure> program when Perl was installed. | |
176 | ||
177 | =item * | |
178 | ||
179 | Choose mnemonic identifiers. If you can't remember what mnemonic means, | |
180 | you've got a problem. | |
181 | ||
54310121 | 182 | =item * |
cb1a09d0 AD |
183 | |
184 | While short identifiers like $gotit are probably ok, use underscores to | |
185 | separate words. It is generally easier to read $var_names_like_this than | |
186 | $VarNamesLikeThis, especially for non-native speakers of English. It's | |
187 | also a simple rule that works consistently with 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 | |
5f05dabc | 193 | file systems' representations of module names as files that must fit into a |
54310121 | 194 | few sparse bytes. |
cb1a09d0 AD |
195 | |
196 | =item * | |
197 | ||
54310121 | 198 | You may find it helpful to use letter case to indicate the scope |
199 | or 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 | 205 | Function and method names seem to work best as all lowercase. |
206 | E.g., $obj-E<gt>as_string(). | |
cb1a09d0 AD |
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 | ||
a0d0e21e LW |
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 "and" and "or" operators to avoid having to parenthesize | |
5f05dabc | 220 | list operators so much, and to reduce the incidence of punctuation |
a0d0e21e | 221 | operators like C<&&> and C<||>. Call your subroutines as if they were |
5f05dabc | 222 | functions or list operators to avoid excessive ampersands and parentheses. |
a0d0e21e LW |
223 | |
224 | =item * | |
225 | ||
226 | Use here documents instead of repeated print() statements. | |
227 | ||
228 | =item * | |
229 | ||
230 | Line up corresponding things vertically, especially if it'd be too long | |
54310121 | 231 | to 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 LW |
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 AD |
244 | Always check the return codes of system calls. Good error messages should |
245 | go to STDERR, include which program caused the problem, what the failed | |
7b8d334a | 246 | system call and arguments were, and (VERY IMPORTANT) should contain the |
cb1a09d0 AD |
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 | ||
2c268ad5 | 254 | Line up your transliterations when it makes sense: |
a0d0e21e LW |
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 | |
9f1b1f2d GS |
264 | code run cleanly with C<use strict> and C<use warnings> (or B<-w>) in effect |
265 | Consider giving away | |
a0d0e21e LW |
266 | your code. Consider changing your whole world view. Consider... oh, |
267 | never mind. | |
268 | ||
269 | =item * | |
270 | ||
271 | Be consistent. | |
272 | ||
273 | =item * | |
274 | ||
275 | Be nice. | |
276 | ||
277 | =back |