Debian Codegraph @

upstream/fedora-44/man1/perlstyle.1

raw
1 .\" -*- mode: troff; coding: utf-8 -*-
2 .\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45)
3 .\"
4 .\" Standard preamble:
5 .\" ========================================================================
6 .de Sp \" Vertical space (when we can't use .PP)
7 .if t .sp .5v
8 .if n .sp
9 ..
10 .de Vb \" Begin verbatim text
11 .ft CW
12 .nf
13 .ne \\$1
14 ..
15 .de Ve \" End verbatim text
16 .ft R
17 .fi
18 ..
19 .\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
20 .ie n \{\
21 . ds C` ""
22 . ds C' ""
23 'br\}
24 .el\{\
25 . ds C`
26 . ds C'
27 'br\}
28 .\"
29 .\" Escape single quotes in literal strings from groff's Unicode transform.
30 .ie \n(.g .ds Aq \(aq
31 .el .ds Aq '
32 .\"
33 .\" If the F register is >0, we'll generate index entries on stderr for
34 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
35 .\" entries marked with X<> in POD. Of course, you'll have to process the
36 .\" output yourself in some meaningful fashion.
37 .\"
38 .\" Avoid warning from groff about undefined register 'F'.
39 .de IX
40 ..
41 .nr rF 0
42 .if \n(.g .if rF .nr rF 1
43 .if (\n(rF:(\n(.g==0)) \{\
44 . if \nF \{\
45 . de IX
46 . tm Index:\\$1\t\\n%\t"\\$2"
47 ..
48 . if !\nF==2 \{\
49 . nr % 0
50 . nr F 2
51 . \}
52 . \}
53 .\}
54 .rr rF
55 .\"
56 .\" Required to disable full justification in groff 1.23.0.
57 .if n .ds AD l
58 .\" ========================================================================
59 .\"
60 .IX Title "PERLSTYLE 1"
61 .TH PERLSTYLE 1 2026-03-09 "perl v5.42.1" "Perl Programmers Reference Guide"
62 .\" For nroff, turn off justification. Always turn off hyphenation; it makes
63 .\" way too many mistakes in technical documents.
64 .if n .ad l
65 .nh
66 .SH NAME
67 perlstyle \- Perl style guide
68 .SH DESCRIPTION
69 .IX Header "DESCRIPTION"
70 Each programmer will, of course, have his or her own preferences in
71 regards to formatting, but there are some general guidelines that will
72 make your programs easier to read, understand, and maintain.
73 .PP
74 The most important thing is to use strict and warnings in all your
75 code or know the reason why not to. You may turn them off explicitly for
76 particular portions of code via \f(CW\*(C`no warnings\*(C'\fR or \f(CW\*(C`no strict\*(C'\fR, and this
77 can be limited to the specific warnings or strict features you wish to
78 disable. The \fB\-w\fR flag and \f(CW$^W\fR variable should not be used for this
79 purpose since they can affect code you use but did not write, such as
80 modules from core or CPAN.
81 .PP
82 A concise way to arrange for this is to use the
83 \&\f(CW\*(C`use VERSION\*(C'\fR syntax, requesting a version 5.36
84 or above, which will enable both the \f(CW\*(C`strict\*(C'\fR and \f(CW\*(C`warnings\*(C'\fR pragmata (as
85 well as several other useful named features).
86 .PP
87 .Vb 1
88 \& use v5.36;
89 .Ve
90 .PP
91 Regarding aesthetics of code layout, about the only thing Larry
92 cares strongly about is that the closing curly bracket of
93 a multi\-line BLOCK should line up with the keyword that started the construct.
94 Beyond that, he has other preferences that aren\*(Aqt so strong:
95 .IP \(bu 4
96 4\-column indent.
97 .IP \(bu 4
98 Opening curly on same line as keyword, if possible, otherwise line up.
99 .IP \(bu 4
100 Space before the opening curly of a multi\-line BLOCK.
101 .IP \(bu 4
102 One\-line BLOCK may be put on one line, including curlies.
103 .IP \(bu 4
104 No space before the semicolon.
105 .IP \(bu 4
106 Semicolon omitted in "short" one\-line BLOCK.
107 .IP \(bu 4
108 Space around most operators.
109 .IP \(bu 4
110 Space around a "complex" subscript (inside brackets).
111 .IP \(bu 4
112 Blank lines between chunks that do different things.
113 .IP \(bu 4
114 Uncuddled elses.
115 .IP \(bu 4
116 No space between function name and its opening parenthesis.
117 .IP \(bu 4
118 Space after each comma.
119 .IP \(bu 4
120 Long lines broken after an operator (except \f(CW\*(C`and\*(C'\fR and \f(CW\*(C`or\*(C'\fR).
121 .IP \(bu 4
122 Space after last parenthesis matching on current line.
123 .IP \(bu 4
124 Line up corresponding items vertically.
125 .IP \(bu 4
126 Omit redundant punctuation as long as clarity doesn\*(Aqt suffer.
127 .PP
128 Larry has his reasons for each of these things, but he doesn\*(Aqt claim that
129 everyone else\*(Aqs mind works the same as his does.
130 .PP
131 Here are some other more substantive style issues to think about:
132 .IP \(bu 4
133 Just because you \fICAN\fR do something a particular way doesn\*(Aqt mean that
134 you \fISHOULD\fR do it that way. Perl is designed to give you several
135 ways to do anything, so consider picking the most readable one. For
136 instance
137 .Sp
138 .Vb 1
139 \& open(my $fh, \*(Aq<\*(Aq, $foo) || die "Can\*(Aqt open $foo: $!";
140 .Ve
141 .Sp
142 is better than
143 .Sp
144 .Vb 1
145 \& die "Can\*(Aqt open $foo: $!" unless open(my $fh, \*(Aq<\*(Aq, $foo);
146 .Ve
147 .Sp
148 because the second way hides the main point of the statement in a
149 modifier. On the other hand
150 .Sp
151 .Vb 1
152 \& print "Starting analysis\en" if $verbose;
153 .Ve
154 .Sp
155 is better than
156 .Sp
157 .Vb 1
158 \& $verbose && print "Starting analysis\en";
159 .Ve
160 .Sp
161 because the main point isn\*(Aqt whether the user typed \fB\-v\fR or not.
162 .Sp
163 Similarly, just because an operator lets you assume default arguments
164 doesn\*(Aqt mean that you have to make use of the defaults. The defaults
165 are there for lazy systems programmers writing one\-shot programs. If
166 you want your program to be readable, consider supplying the argument.
167 .Sp
168 Along the same lines, just because you \fICAN\fR omit parentheses in many
169 places doesn\*(Aqt mean that you ought to:
170 .Sp
171 .Vb 2
172 \& return print reverse sort num values %array;
173 \& return print(reverse(sort num (values(%array))));
174 .Ve
175 .Sp
176 When in doubt, parenthesize. At the very least it will let some poor
177 schmuck bounce on the % key in \fBvi\fR.
178 .Sp
179 Even if you aren\*(Aqt in doubt, consider the mental welfare of the person
180 who has to maintain the code after you, and who will probably put
181 parentheses in the wrong place.
182 .IP \(bu 4
183 Don\*(Aqt go through silly contortions to exit a loop at the top or the
184 bottom, when Perl provides the \f(CW\*(C`last\*(C'\fR operator so you can exit in
185 the middle. Just "outdent" it a little to make it more visible:
186 .Sp
187 .Vb 7
188 \& LINE:
189 \& for (;;) {
190 \& statements;
191 \& last LINE if $foo;
192 \& next LINE if /^#/;
193 \& statements;
194 \& }
195 .Ve
196 .IP \(bu 4
197 Don\*(Aqt be afraid to use loop labels\-\-they\*(Aqre there to enhance
198 readability as well as to allow multilevel loop breaks. See the
199 previous example.
200 .IP \(bu 4
201 Avoid using \f(CWgrep()\fR (or \f(CWmap()\fR) or \`backticks\` in a void context, that is,
202 when you just throw away their return values. Those functions all
203 have return values, so use them. Otherwise use a \f(CWforeach()\fR loop or
204 the \f(CWsystem()\fR function instead.
205 .IP \(bu 4
206 For portability, when using features that may not be implemented on
207 every machine, test the construct in an eval to see if it fails. If
208 you know what version or patchlevel a particular feature was
209 implemented, you can test \f(CW$]\fR (\f(CW$PERL_VERSION\fR in \f(CW\*(C`English\*(C'\fR) to see if it
210 will be there. The \f(CW\*(C`Config\*(C'\fR module will also let you interrogate values
211 determined by the \fBConfigure\fR program when Perl was installed.
212 .IP \(bu 4
213 Choose mnemonic identifiers. If you can\*(Aqt remember what mnemonic means,
214 you\*(Aqve got a problem.
215 .IP \(bu 4
216 While short identifiers like \f(CW$gotit\fR are probably ok, use underscores to
217 separate words in longer identifiers. It is generally easier to read
218 \&\f(CW$var_names_like_this\fR than \f(CW$VarNamesLikeThis\fR, especially for
219 non\-native speakers of English. It\*(Aqs also a simple rule that works
220 consistently with \f(CW\*(C`VAR_NAMES_LIKE_THIS\*(C'\fR.
221 .Sp
222 Package names are sometimes an exception to this rule. Perl informally
223 reserves lowercase module names for "pragma" modules like \f(CW\*(C`integer\*(C'\fR and
224 \&\f(CW\*(C`strict\*(C'\fR. Other modules should begin with a capital letter and use mixed
225 case, but probably without underscores due to limitations in primitive
226 file systems\*(Aq representations of module names as files that must fit into a
227 few sparse bytes.
228 .IP \(bu 4
229 You may find it helpful to use letter case to indicate the scope
230 or nature of a variable. For example:
231 .Sp
232 .Vb 3
233 \& $ALL_CAPS_HERE constants only (beware clashes with perl vars!)
234 \& $Some_Caps_Here package\-wide global/static
235 \& $no_caps_here function scope my() or local() variables
236 .Ve
237 .Sp
238 Function and method names seem to work best as all lowercase.
239 E.g., \f(CW\*(C`$obj\->as_string()\*(C'\fR.
240 .Sp
241 You can use a leading underscore to indicate that a variable or
242 function should not be used outside the package that defined it.
243 .IP \(bu 4
244 If you have a really hairy regular expression, use the \f(CW\*(C`/x\*(C'\fR or \f(CW\*(C`/xx\*(C'\fR
245 modifiers and put in some whitespace to make it look a little less like
246 line noise.
247 Don\*(Aqt use slash as a delimiter when your regexp has slashes or backslashes.
248 .IP \(bu 4
249 Use the \f(CW\*(C`and\*(C'\fR and \f(CW\*(C`or\*(C'\fR operators to avoid having to parenthesize
250 list operators so much, and to reduce the incidence of punctuation
251 operators like \f(CW\*(C`&&\*(C'\fR and \f(CW\*(C`||\*(C'\fR. Call your subroutines as if they were
252 functions or list operators to avoid excessive ampersands and parentheses.
253 .IP \(bu 4
254 Use here documents instead of repeated \f(CWprint()\fR statements.
255 .IP \(bu 4
256 Line up corresponding things vertically, especially if it\*(Aqd be too long
257 to fit on one line anyway.
258 .Sp
259 .Vb 4
260 \& $IDX = $ST_MTIME;
261 \& $IDX = $ST_ATIME if $opt_u;
262 \& $IDX = $ST_CTIME if $opt_c;
263 \& $IDX = $ST_SIZE if $opt_s;
264 \&
265 \& mkdir $tmpdir, 0700 or die "can\*(Aqt mkdir $tmpdir: $!";
266 \& chdir($tmpdir) or die "can\*(Aqt chdir $tmpdir: $!";
267 \& mkdir \*(Aqtmp\*(Aq, 0777 or die "can\*(Aqt mkdir $tmpdir/tmp: $!";
268 .Ve
269 .IP \(bu 4
270 Always check the return codes of system calls. Good error messages should
271 go to \f(CW\*(C`STDERR\*(C'\fR, include which program caused the problem, what the failed
272 system call and arguments were, and (VERY IMPORTANT) should contain the
273 standard system error message for what went wrong. Here\*(Aqs a simple but
274 sufficient example:
275 .Sp
276 .Vb 1
277 \& opendir(my $dh, $dir) or die "can\*(Aqt opendir $dir: $!";
278 .Ve
279 .IP \(bu 4
280 Line up your transliterations when it makes sense:
281 .Sp
282 .Vb 2
283 \& tr [abc]
284 \& [xyz];
285 .Ve
286 .IP \(bu 4
287 Think about reusability. Why waste brainpower on a one\-shot when you
288 might want to do something like it again? Consider generalizing your
289 code. Consider writing a module or object class. Consider making your
290 code run cleanly with \f(CW\*(C`use strict\*(C'\fR and \f(CW\*(C`use warnings\*(C'\fR in
291 effect. Consider giving away your code. Consider changing your whole
292 world view. Consider... oh, never mind.
293 .IP \(bu 4
294 Try to document your code and use Pod formatting in a consistent way. Here
295 are commonly expected conventions:
296 .RS 4
297 .IP \(bu 4
298 use \f(CW\*(C`C<>\*(C'\fR for function, variable and module names (and more
299 generally anything that can be considered part of code, like filehandles
300 or specific values). Note that function names are considered more readable
301 with parentheses after their name, that is \f(CWfunction()\fR.
302 .IP \(bu 4
303 use \f(CW\*(C`B<>\*(C'\fR for commands names like \fBcat\fR or \fBgrep\fR.
304 .IP \(bu 4
305 use \f(CW\*(C`F<>\*(C'\fR or \f(CW\*(C`C<>\*(C'\fR for file names. \f(CW\*(C`F<>\*(C'\fR should
306 be the only Pod code for file names, but as most Pod formatters render it
307 as italic, Unix and Windows paths with their slashes and backslashes may
308 be less readable, and better rendered with \f(CW\*(C`C<>\*(C'\fR.
309 .RE
310 .RS 4
311 .RE
312 .IP \(bu 4
313 Be consistent.
314 .IP \(bu 4
315 Be nice.