Commit | Line | Data |
a0d0e21e |
1 | =head1 NAME |
2 | |
3 | perlstyle - Perl style guide |
4 | |
5 | =head1 DESCRIPTION |
6 | |
a0d0e21e |
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 |
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 |
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 |
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 |
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 |
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 |
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 |
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 |
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 |
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 |
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 |
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 |
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 |
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 |
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 |
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 |
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 |
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 |
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 |
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 |
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 |
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 |
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 |
264 | code run cleanly with C<use strict> and C<use warnings> (or B<-w>) in effect |
265 | Consider giving away |
a0d0e21e |
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 |