Commit | Line | Data |
---|---|---|
a0d0e21e LW |
1 | =head1 NAME |
2 | ||
3 | perlstyle - Perl style guide | |
4 | ||
5 | =head1 DESCRIPTION | |
6 | ||
7 | =head2 Style | |
8 | ||
9 | Each programmer will, of course, have his or her own preferences in | |
10 | regards to formatting, but there are some general guidelines that will | |
11 | make your programs easier to read, understand, and maintain. | |
12 | ||
13 | Regarding aesthetics of code lay out, about the only thing Larry | |
14 | cares strongly about is that the closing curly brace of | |
15 | a multi-line BLOCK should line up with the keyword that started the construct. | |
16 | Beyond that, he has other preferences that aren't so strong: | |
17 | ||
18 | =over 4 | |
19 | ||
20 | =item * | |
21 | ||
22 | 4-column indent. | |
23 | ||
24 | =item * | |
25 | ||
26 | Opening curly on same line as keyword, if possible, otherwise line up. | |
27 | ||
28 | =item * | |
29 | ||
30 | Space before the opening curly of a multiline BLOCK. | |
31 | ||
32 | =item * | |
33 | ||
34 | One-line BLOCK may be put on one line, including curlies. | |
35 | ||
36 | =item * | |
37 | ||
38 | No space before the semicolon. | |
39 | ||
40 | =item * | |
41 | ||
42 | Semicolon omitted in "short" one-line BLOCK. | |
43 | ||
44 | =item * | |
45 | ||
46 | Space around most operators. | |
47 | ||
48 | =item * | |
49 | ||
50 | Space around a "complex" subscript (inside brackets). | |
51 | ||
52 | =item * | |
53 | ||
54 | Blank lines between chunks that do different things. | |
55 | ||
56 | =item * | |
57 | ||
58 | Uncuddled elses. | |
59 | ||
60 | =item * | |
61 | ||
62 | No space between function name and its opening paren. | |
63 | ||
64 | =item * | |
65 | ||
66 | Space after each comma. | |
67 | ||
68 | =item * | |
69 | ||
70 | Long lines broken after an operator (except "and" and "or"). | |
71 | ||
72 | =item * | |
73 | ||
74 | Space after last paren matching on current line. | |
75 | ||
76 | =item * | |
77 | ||
78 | Line up corresponding items vertically. | |
79 | ||
80 | =item * | |
81 | ||
82 | Omit redundant punctuation as long as clarity doesn't suffer. | |
83 | ||
84 | =back | |
85 | ||
86 | Larry has his reasons for each of these things, but he doen't claim that | |
87 | everyone else's mind works the same as his does. | |
88 | ||
89 | Here are some other more substantive style issues to think about: | |
90 | ||
91 | =over 4 | |
92 | ||
93 | =item * | |
94 | ||
95 | Just because you I<CAN> do something a particular way doesn't mean that | |
96 | you I<SHOULD> do it that way. Perl is designed to give you several | |
97 | ways to do anything, so consider picking the most readable one. For | |
98 | instance | |
99 | ||
100 | open(FOO,$foo) || die "Can't open $foo: $!"; | |
101 | ||
102 | is better than | |
103 | ||
104 | die "Can't open $foo: $!" unless open(FOO,$foo); | |
105 | ||
106 | because the second way hides the main point of the statement in a | |
107 | modifier. On the other hand | |
108 | ||
109 | print "Starting analysis\n" if $verbose; | |
110 | ||
111 | is better than | |
112 | ||
113 | $verbose && print "Starting analysis\n"; | |
114 | ||
115 | since the main point isn't whether the user typed B<-v> or not. | |
116 | ||
117 | Similarly, just because an operator lets you assume default arguments | |
118 | doesn't mean that you have to make use of the defaults. The defaults | |
119 | are there for lazy systems programmers writing one-shot programs. If | |
120 | you want your program to be readable, consider supplying the argument. | |
121 | ||
122 | Along the same lines, just because you I<CAN> omit parentheses in many | |
123 | places doesn't mean that you ought to: | |
124 | ||
125 | return print reverse sort num values %array; | |
126 | return print(reverse(sort num (values(%array)))); | |
127 | ||
128 | When in doubt, parenthesize. At the very least it will let some poor | |
129 | schmuck bounce on the % key in B<vi>. | |
130 | ||
131 | Even if you aren't in doubt, consider the mental welfare of the person | |
132 | who has to maintain the code after you, and who will probably put | |
133 | parens in the wrong place. | |
134 | ||
135 | =item * | |
136 | ||
137 | Don't go through silly contortions to exit a loop at the top or the | |
138 | bottom, when Perl provides the C<last> operator so you can exit in | |
139 | the middle. Just "outdent" it a little to make it more visible: | |
140 | ||
141 | LINE: | |
142 | for (;;) { | |
143 | statements; | |
144 | last LINE if $foo; | |
145 | next LINE if /^#/; | |
146 | statements; | |
147 | } | |
148 | ||
149 | =item * | |
150 | ||
151 | Don't be afraid to use loop labels--they're there to enhance | |
152 | readability as well as to allow multi-level loop breaks. See the | |
153 | previous example. | |
154 | ||
155 | =item * | |
156 | ||
157 | For portability, when using features that may not be implemented on | |
158 | every machine, test the construct in an eval to see if it fails. If | |
159 | you know what version or patchlevel a particular feature was | |
160 | implemented, you can test C<$]> ($PERL_VERSION in C<English>) to see if it | |
161 | will be there. The C<Config> module will also let you interrogate values | |
162 | determined by the B<Configure> program when Perl was installed. | |
163 | ||
164 | =item * | |
165 | ||
166 | Choose mnemonic identifiers. If you can't remember what mnemonic means, | |
167 | you've got a problem. | |
168 | ||
169 | =item * | |
170 | ||
171 | If you have a really hairy regular expression, use the C</x> modifier and | |
172 | put in some whitespace to make it look a little less like line noise. | |
173 | Don't use slash as a delimiter when your regexp has slashes or backslashes. | |
174 | ||
175 | =item * | |
176 | ||
177 | Use the new "and" and "or" operators to avoid having to parenthesize | |
178 | list operators so much, and to reduce the incidence of punctuational | |
179 | operators like C<&&> and C<||>. Call your subroutines as if they were | |
180 | functions or list operators to avoid excessive ampersands and parens. | |
181 | ||
182 | =item * | |
183 | ||
184 | Use here documents instead of repeated print() statements. | |
185 | ||
186 | =item * | |
187 | ||
188 | Line up corresponding things vertically, especially if it'd be too long | |
189 | to fit on one line anyway. | |
190 | ||
191 | $IDX = $ST_MTIME; | |
192 | $IDX = $ST_ATIME if $opt_u; | |
193 | $IDX = $ST_CTIME if $opt_c; | |
194 | $IDX = $ST_SIZE if $opt_s; | |
195 | ||
196 | mkdir $tmpdir, 0700 or die "can't mkdir $tmpdir: $!"; | |
197 | chdir($tmpdir) or die "can't chdir $tmpdir: $!"; | |
198 | mkdir 'tmp', 0777 or die "can't mkdir $tmpdir/tmp: $!"; | |
199 | ||
200 | =item * | |
201 | ||
202 | Line up your translations when it makes sense: | |
203 | ||
204 | tr [abc] | |
205 | [xyz]; | |
206 | ||
207 | =item * | |
208 | ||
209 | Think about reusability. Why waste brainpower on a one-shot when you | |
210 | might want to do something like it again? Consider generalizing your | |
211 | code. Consider writing a module or object class. Consider making your | |
212 | code run cleanly with C<use strict> and B<-w> in effect. Consider giving away | |
213 | your code. Consider changing your whole world view. Consider... oh, | |
214 | never mind. | |
215 | ||
216 | =item * | |
217 | ||
218 | Be consistent. | |
219 | ||
220 | =item * | |
221 | ||
222 | Be nice. | |
223 | ||
224 | =back | |
225 |