home *** CD-ROM | disk | FTP | other *** search
- <!-- $RCSfile$$Revision$$Date$ -->
- <!-- $Log$ -->
- <HTML>
- <TITLE> PERLSTYLE </TITLE>
- <h2>NAME</h2>
- perlstyle - Perl style guide
- <p><h2>DESCRIPTION</h2>
- <h3>Style</h3>
- Each programmer will, of course, have his or her own preferences in
- regards to formatting, but there are some general guidelines that will
- make your programs easier to read, understand, and maintain.
- <p>Regarding aesthetics of code lay out, about the only thing Larry
- cares strongly about is that the closing curly brace of
- a multi-line BLOCK should line up with the keyword that started the construct.
- Beyond that, he has other preferences that aren't so strong:
- <p>
- <dl>
-
- <dt><b><A NAME="perlcall_39">*</A></b>
- <dd>
- 4-column indent.
- <p></dd>
- <dt><B>*</B>
- <dd>
- Opening curly on same line as keyword, if possible, otherwise line up.
- <p></dd>
- <dt><B>*</B>
- <dd>
- Space before the opening curly of a multiline BLOCK.
- <p></dd>
- <dt><B>*</B>
- <dd>
- One-line BLOCK may be put on one line, including curlies.
- <p></dd>
- <dt><B>*</B>
- <dd>
- No space before the semicolon.
- <p></dd>
- <dt><B>*</B>
- <dd>
- Semicolon omitted in "short" one-line BLOCK.
- <p></dd>
- <dt><B>*</B>
- <dd>
- Space around most operators.
- <p></dd>
- <dt><B>*</B>
- <dd>
- Space around a "complex" subscript (inside brackets).
- <p></dd>
- <dt><B>*</B>
- <dd>
- Blank lines between chunks that do different things.
- <p></dd>
- <dt><B>*</B>
- <dd>
- Uncuddled elses.
- <p></dd>
- <dt><B>*</B>
- <dd>
- No space between function name and its opening paren.
- <p></dd>
- <dt><B>*</B>
- <dd>
- Space after each comma.
- <p></dd>
- <dt><B>*</B>
- <dd>
- Long lines broken after an operator (except "and" and "or").
- <p></dd>
- <dt><B>*</B>
- <dd>
- Space after last paren matching on current line.
- <p></dd>
- <dt><B>*</B>
- <dd>
- Line up corresponding items vertically.
- <p></dd>
- <dt><B>*</B>
- <dd>
- Omit redundant punctuation as long as clarity doesn't suffer.
- <p></dd>
-
- </dl>
-
- Larry has his reasons for each of these things, but he doen't claim that
- everyone else's mind works the same as his does.
- <p>Here are some other more substantive style issues to think about:
- <p>
- <dl>
- <dt><B>*</B>
- <dd>
- Just because you <I>CAN</I> do something a particular way doesn't mean that
- you <I>SHOULD</I> do it that way. Perl is designed to give you several
- ways to do anything, so consider picking the most readable one. For
- instance
- <p></dd>
- <pre>
- open(FOO,$foo) || die "Can't open $foo: $!";
- </pre>
- is better than
- <p><pre>
- die "Can't open $foo: $!" unless open(FOO,$foo);
- </pre>
- because the second way hides the main point of the statement in a
- modifier. On the other hand
- <p><pre>
- print "Starting analysis\n" if $verbose;
- </pre>
- is better than
- <p><pre>
- $verbose && print "Starting analysis\n";
- </pre>
- since the main point isn't whether the user typed
- <A HREF="perlrun.html#perlrun_361">-v</A>
- or not.
- <p>Similarly, just because an operator lets you assume default arguments
- doesn't mean that you have to make use of the defaults. The defaults
- are there for lazy systems programmers writing one-shot programs. If
- you want your program to be readable, consider supplying the argument.
- <p>Along the same lines, just because you <I>CAN</I> omit parentheses in many
- places doesn't mean that you ought to:
- <p><pre>
- return print reverse sort num values %array;
- return print(reverse(sort num (values(%array))));
- </pre>
- When in doubt, parenthesize. At the very least it will let some poor
- schmuck bounce on the % key in <B>vi</B>.
- <p>Even if you aren't in doubt, consider the mental welfare of the person
- who has to maintain the code after you, and who will probably put
- parens in the wrong place.
- <p><dt><B>*</B>
- <dd>
- Don't go through silly contortions to exit a loop at the top or the
- bottom, when Perl provides the
- <A HREF="perlfunc.html#perlfunc_161">last</A>
- operator so you can exit in
- the middle. Just "outdent" it a little to make it more visible:
- <p></dd>
- <pre>
- LINE:
- for (;;) {
- statements;
- last LINE if $foo;
- next LINE if /^#/;
- statements;
- }
- </pre>
- <dt><B>*</B>
- <dd>
- Don't be afraid to use loop labels--they're there to enhance
- readability as well as to allow multi-level loop breaks. See the
- previous example.
- <p></dd>
- <dt><B>*</B>
- <dd>
- For portability, when using features that may not be implemented on
- every machine, test the construct in an eval to see if it fails. If
- you know what version or patchlevel a particular feature was
- implemented, you can test
- <A HREF="perlvar.html#perlvar_458">$]</A>
- ($PERL_VERSION in <B>English</B>) to see if it
- will be there. The <B>Config</B> module will also let you interrogate values
- determined by the <B>Configure</B> program when Perl was installed.
- <p></dd>
- <dt><B>*</B>
- <dd>
- Choose mnemonic identifiers. If you can't remember what mnemonic means,
- you've got a problem.
- <p></dd>
- <dt><B>*</B>
- <dd>
- If you have a really hairy regular expression, use the <B>/x</B> modifier and
- put in some whitespace to make it look a little less like line noise.
- Don't use slash as a delimiter when your regexp has slashes or backslashes.
- <p></dd>
- <dt><B>*</B>
- <dd>
- Use the new "and" and "or" operators to avoid having to parenthesize
- list operators so much, and to reduce the incidence of punctuational
- operators like <B>&&</B> and <B>||</B>. Call your subroutines as if they were
- functions or list operators to avoid excessive ampersands and parens.
- <p></dd>
- <dt><B>*</B>
- <dd>
- Use here documents instead of repeated print() statements.
- <p></dd>
- <dt><B>*</B>
- <dd>
- Line up corresponding things vertically, especially if it'd be too long
- to fit on one line anyway.
- <p></dd>
- <pre>
- $IDX = $ST_MTIME;
- $IDX = $ST_ATIME if $opt_u;
- $IDX = $ST_CTIME if $opt_c;
- $IDX = $ST_SIZE if $opt_s;
- </pre>
- <pre>
- mkdir $tmpdir, 0700 or die "can't mkdir $tmpdir: $!";
- chdir($tmpdir) or die "can't chdir $tmpdir: $!";
- mkdir 'tmp', 0777 or die "can't mkdir $tmpdir/tmp: $!";
- </pre>
- <dt><B>*</B>
- <dd>
- Line up your translations when it makes sense:
- <p></dd>
- <pre>
- tr [abc]
- [xyz];
- </pre>
- <dt><B>*</B>
- <dd>
- Think about reusability. Why waste brainpower on a one-shot when you
- might want to do something like it again? Consider generalizing your
- code. Consider writing a module or object class. Consider making your
- code run cleanly with <B>use strict</B> and
- <A HREF="perlrun.html#perlrun_362">-w</A>
- in effect. Consider giving away
- your code. Consider changing your whole world view. Consider... oh,
- never mind.
- <p></dd>
- <dt><B>*</B>
- <dd>
- Be consistent.
- <p></dd>
- <dt><B>*</B>
- <dd>
- Be nice.
- <p></dd>
-
- </dl>
-
-