Commit | Line | Data |
a0d0e21e |
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 | |