Penguin
Hide Sidebar Hide Ads Recent Changes
Blame: perlstyle(1)
EditPageHistoryDiffInfoLikePages
Annotated edit history of perlstyle(1) version 2, including all changes. View license author blame.
Rev Author # Line
1 perry 1 PERLSTYLE
2 !!!PERLSTYLE
3 NAME
4 DESCRIPTION
5 ----
6 !!NAME
7
8
9 perlstyle - Perl style guide
10 !!DESCRIPTION
11
12
13 Each programmer will, of course, have his or her own
14 preferences in regards to formatting, but there are some
15 general guidelines that will make your programs easier to
16 read, understand, and maintain.
17
18
19 The most important thing is to run your programs under the
20 __-w__ flag at all times. You may turn it off explicitly
21 for particular portions of code via the use
22 warnings pragma or the $^W variable if you
23 must. You should also always run under use strict
24 or know the reason why not. The use sigtrap and
25 even use diagnostics pragmas may also prove
26 useful.
27
28
29 Regarding aesthetics of code lay out, about the only thing
30 Larry cares strongly about is that the closing curly bracket
31 of a multi-line BLOCK should line up with the
32 keyword that started the construct. Beyond that, he has
33 other preferences that aren't so strong:
34
35
36 4-column indent.
37
38
39 Opening curly on same line as keyword, if possible,
40 otherwise line up.
41
42
43 Space before the opening curly of a multi-line
44 BLOCK .
45
46
47 One-line BLOCK may be put on one line,
48 including curlies.
49
50
51 No space before the semicolon.
52
53
54 Semicolon omitted in ``short'' one-line BLOCK
55 .
56
57
58 Space around most operators.
59
60
61 Space around a ``complex'' subscript (inside
62 brackets).
63
64
65 Blank lines between chunks that do different
66 things.
67
68
69 Uncuddled elses.
70
71
72 No space between function name and its opening
73 parenthesis.
74
75
76 Space after each comma.
77
78
79 Long lines broken after an operator (except ``and'' and
80 ``or'').
81
82
83 Space after last parenthesis matching on current
84 line.
85
86
87 Line up corresponding items vertically.
88
89
90 Omit redundant punctuation as long as clarity doesn't
91 suffer.
92
93
94 Larry has his reasons for each of these things, but he
95 doesn't claim that everyone else's mind works the same as
96 his does.
97
98
99 Here are some other more substantive style issues to think
100 about:
101
102
103 Just because you ''CAN'' do something a
104 particular way doesn't mean that you
105 ''SHOULD'' do it that way. Perl is
106 designed to give you several ways to do anything, so
107 consider picking the most readable one. For
108 instance
109
110
111 open(FOO,$foo) die
112 is better than
113
114
115 die
116 because the second way hides the main point of the statement in a modifier. On the other hand
117
118
119 print
120 is better than
121
122
123 $verbose
124 because the main point isn't whether the user typed __-v__ or not.
125
126
127 Similarly, just because an operator lets you assume default
128 arguments doesn't mean that you have to make use of the
129 defaults. The defaults are there for lazy systems
130 programmers writing one-shot programs. If you want your
131 program to be readable, consider supplying the
132 argument.
133
134
135 Along the same lines, just because you
136 ''CAN'' omit parentheses in many places
137 doesn't mean that you ought to:
138
139
140 return print reverse sort num values %array;
141 return print(reverse(sort num (values(%array))));
142 When in doubt, parenthesize. At the very least it will let some poor schmuck bounce on the % key in __vi__.
143
144
145 Even if you aren't in doubt, consider the mental welfare of
146 the person who has to maintain the code after you, and who
147 will probably put parentheses in the wrong
148 place.
149
150
151 Don't go through silly contortions to exit a loop at the top
152 or the bottom, when Perl provides the last operator
153 so you can exit in the middle. Just ``outdent'' it a little
154 to make it more visible:
155
156
157 LINE:
158 for (;;) {
159 statements;
160 last LINE if $foo;
161 next LINE if /^#/;
162 statements;
163 }
164
165
166 Don't be afraid to use loop labels--they're there to enhance
167 readability as well as to allow multilevel loop breaks. See
168 the previous example.
169
170
171 Avoid using ''grep()'' (or ''map()'') or `backticks`
172 in a void context, that is, when you just throw away their
173 return values. Those functions all have return values, so
174 use them. Otherwise use a ''foreach()'' loop or the
175 ''system()'' function instead.
176
177
178 For portability, when using features that may not be
179 implemented on every machine, test the construct in an eval
180 to see if it fails. If you know what version or patchlevel a
181 particular feature was implemented, you can test $]
182 ($PERL_VERSION in English) to see if it
183 will be there. The Config module will also let you
184 interrogate values determined by the __Configure__
185 program when Perl was installed.
186
187
188 Choose mnemonic identifiers. If you can't remember what
189 mnemonic means, you've got a problem.
190
191
192 While short identifiers like $gotit are probably
193 ok, use underscores to separate words. It is generally
194 easier to read $var_names_like_this than
2 perry 195 $!VarNamesLikeThis, especially for non-native
1 perry 196 speakers of English. It's also a simple rule that works
197 consistently with VAR_NAMES_LIKE_THIS
198 .
199
200
201 Package names are sometimes an exception to this rule. Perl
202 informally reserves lowercase module names for ``pragma''
203 modules like integer and strict. Other
204 modules should begin with a capital letter and use mixed
205 case, but probably without underscores due to limitations in
206 primitive file systems' representations of module names as
207 files that must fit into a few sparse bytes.
208
209
210 You may find it helpful to use letter case to indicate the
211 scope or nature of a variable. For example:
212
213
214 $ALL_CAPS_HERE constants only (beware clashes with perl vars!)
215 $Some_Caps_Here package-wide global/static
216 $no_caps_here function scope my() or local() variables
217 Function and method names seem to work best as all lowercase. E.g., $obj-as_string()''.
218
219
220 You can use a leading underscore to indicate that a variable
221 or function should not be used outside the package that
222 defined it.
223
224
225 If you have a really hairy regular expression, use the
226 /x modifier and put in some whitespace to make it
227 look a little less like line noise. Don't use slash as a
228 delimiter when your regexp has slashes or
229 backslashes.
230
231
232 Use the new ``and'' and ``or'' operators to avoid having to
233 parenthesize list operators so much, and to reduce the
234 incidence of punctuation operators like
235 and . Call your subroutines as if they were functions or
236 list operators to avoid excessive ampersands and
237 parentheses.
238
239
240 Use here documents instead of repeated ''print()''
241 statements.
242
243
244 Line up corresponding things vertically, especially if it'd
245 be too long to fit on one line anyway.
246
247
248 $IDX = $ST_MTIME;
249 $IDX = $ST_ATIME if $opt_u;
250 $IDX = $ST_CTIME if $opt_c;
251 $IDX = $ST_SIZE if $opt_s;
252 mkdir $tmpdir, 0700 or die
253
254
255 Always check the return codes of system calls. Good error
256 messages should go to STDERR , include which
257 program caused the problem, what the failed system call and
258 arguments were, and ( VERY IMPORTANT ) should
259 contain the standard system error message for what went
260 wrong. Here's a simple but sufficient example:
261
262
263 opendir(D, $dir) or die
264
265
266 Line up your transliterations when it makes
267 sense:
268
269
270 tr [[abc]
271 [[xyz];
272
273
274 Think about reusability. Why waste brainpower on a one-shot
275 when you might want to do something like it again? Consider
276 generalizing your code. Consider writing a module or object
277 class. Consider making your code run cleanly with use
278 strict and use warnings (or __-w__) in
279 effect Consider giving away your code. Consider changing
280 your whole world view. Consider... oh, never
281 mind.
282
283
284 Be consistent.
285
286
287 Be nice.
288 ----
This page is a man page (or other imported legacy content). We are unable to automatically determine the license status of this page.