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 | |
0c506aae AT |
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. | |
cb1a09d0 | 17 | |
a0d0e21e | 18 | Regarding aesthetics of code lay out, about the only thing Larry |
d98d5fff | 19 | cares strongly about is that the closing curly bracket of |
4a6725af | 20 | a multi-line BLOCK should line up with the keyword that started the construct. |
a0d0e21e LW |
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 | ||
4a6725af | 35 | Space before the opening curly of a multi-line BLOCK. |
a0d0e21e LW |
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 | ||
5f05dabc | 67 | No space between function name and its opening parenthesis. |
a0d0e21e LW |
68 | |
69 | =item * | |
70 | ||
71 | Space after each comma. | |
72 | ||
73 | =item * | |
74 | ||
75 | Long lines broken after an operator (except "and" and "or"). | |
76 | ||
77 | =item * | |
78 | ||
5f05dabc | 79 | Space after last parenthesis matching on current line. |
a0d0e21e LW |
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 | ||
184e9718 | 91 | Larry has his reasons for each of these things, but he doesn't claim that |
a0d0e21e LW |
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 | ||
5f05dabc | 120 | because the main point isn't whether the user typed B<-v> or not. |
a0d0e21e LW |
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 | |
5f05dabc | 138 | parentheses in the wrong place. |
a0d0e21e LW |
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 | |
54310121 | 157 | readability as well as to allow multilevel loop breaks. See the |
a0d0e21e LW |
158 | previous example. |
159 | ||
160 | =item * | |
161 | ||
c07a80fd | 162 | Avoid using grep() (or map()) or `backticks` in a void context, that is, |
54310121 | 163 | when you just throw away their return values. Those functions all |
c07a80fd | 164 | have return values, so use them. Otherwise use a foreach() loop or |
165 | the system() function instead. | |
166 | ||
167 | =item * | |
168 | ||
a0d0e21e LW |
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 | |
184e9718 | 172 | implemented, you can test C<$]> (C<$PERL_VERSION> in C<English>) to see if it |
a0d0e21e LW |
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 | ||
54310121 | 181 | =item * |
cb1a09d0 AD |
182 | |
183 | While short identifiers like $gotit are probably ok, use underscores to | |
184 | separate words. It is generally easier to read $var_names_like_this than | |
185 | $VarNamesLikeThis, especially for non-native speakers of English. It's | |
186 | also a simple rule that works consistently with VAR_NAMES_LIKE_THIS. | |
187 | ||
188 | Package names are sometimes an exception to this rule. Perl informally | |
189 | reserves lowercase module names for "pragma" modules like C<integer> and | |
190 | C<strict>. Other modules should begin with a capital letter and use mixed | |
191 | case, but probably without underscores due to limitations in primitive | |
5f05dabc | 192 | file systems' representations of module names as files that must fit into a |
54310121 | 193 | few sparse bytes. |
cb1a09d0 AD |
194 | |
195 | =item * | |
196 | ||
54310121 | 197 | You may find it helpful to use letter case to indicate the scope |
198 | or 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 | 204 | Function and method names seem to work best as all lowercase. |
205 | E.g., $obj-E<gt>as_string(). | |
cb1a09d0 AD |
206 | |
207 | You can use a leading underscore to indicate that a variable or | |
208 | function should not be used outside the package that defined it. | |
209 | ||
a0d0e21e LW |
210 | =item * |
211 | ||
212 | If you have a really hairy regular expression, use the C</x> modifier and | |
213 | put in some whitespace to make it look a little less like line noise. | |
214 | Don't use slash as a delimiter when your regexp has slashes or backslashes. | |
215 | ||
216 | =item * | |
217 | ||
218 | Use the new "and" and "or" operators to avoid having to parenthesize | |
5f05dabc | 219 | list operators so much, and to reduce the incidence of punctuation |
a0d0e21e | 220 | operators like C<&&> and C<||>. Call your subroutines as if they were |
5f05dabc | 221 | functions or list operators to avoid excessive ampersands and parentheses. |
a0d0e21e LW |
222 | |
223 | =item * | |
224 | ||
225 | Use here documents instead of repeated print() statements. | |
226 | ||
227 | =item * | |
228 | ||
229 | Line up corresponding things vertically, especially if it'd be too long | |
54310121 | 230 | to 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 LW |
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 AD |
243 | Always check the return codes of system calls. Good error messages should |
244 | go to STDERR, include which program caused the problem, what the failed | |
7b8d334a | 245 | system call and arguments were, and (VERY IMPORTANT) should contain the |
cb1a09d0 AD |
246 | standard system error message for what went wrong. Here's a simple but |
247 | sufficient example: | |
248 | ||
249 | opendir(D, $dir) or die "can't opendir $dir: $!"; | |
250 | ||
251 | =item * | |
252 | ||
2c268ad5 | 253 | Line up your transliterations when it makes sense: |
a0d0e21e LW |
254 | |
255 | tr [abc] | |
256 | [xyz]; | |
257 | ||
258 | =item * | |
259 | ||
260 | Think about reusability. Why waste brainpower on a one-shot when you | |
261 | might want to do something like it again? Consider generalizing your | |
262 | code. Consider writing a module or object class. Consider making your | |
0c506aae AT |
263 | code run cleanly with C<use strict> and C<use warnings> (or B<-w>) in |
264 | effect. Consider giving away your code. Consider changing your whole | |
265 | world view. Consider... oh, never mind. | |
a0d0e21e LW |
266 | |
267 | =item * | |
268 | ||
269 | Be consistent. | |
270 | ||
271 | =item * | |
272 | ||
273 | Be nice. | |
274 | ||
275 | =back |