diff options
Diffstat (limited to 'contrib/perl5/pod/perlstyle.pod')
| -rw-r--r-- | contrib/perl5/pod/perlstyle.pod | 277 |
1 files changed, 0 insertions, 277 deletions
diff --git a/contrib/perl5/pod/perlstyle.pod b/contrib/perl5/pod/perlstyle.pod deleted file mode 100644 index bfe5b76..0000000 --- a/contrib/perl5/pod/perlstyle.pod +++ /dev/null @@ -1,277 +0,0 @@ -=head1 NAME - -perlstyle - Perl style guide - -=head1 DESCRIPTION - -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. - -The most important thing is to run your programs under the B<-w> -flag at all times. You may turn it off explicitly for particular -portions of code via the C<use warnings> pragma or the C<$^W> variable -if you must. You should -also always run under C<use strict> or know the reason why not. -The C<use sigtrap> and even C<use diagnostics> pragmas may also prove -useful. - -Regarding aesthetics of code lay out, about the only thing Larry -cares strongly about is that the closing curly bracket 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: - -=over 4 - -=item * - -4-column indent. - -=item * - -Opening curly on same line as keyword, if possible, otherwise line up. - -=item * - -Space before the opening curly of a multi-line BLOCK. - -=item * - -One-line BLOCK may be put on one line, including curlies. - -=item * - -No space before the semicolon. - -=item * - -Semicolon omitted in "short" one-line BLOCK. - -=item * - -Space around most operators. - -=item * - -Space around a "complex" subscript (inside brackets). - -=item * - -Blank lines between chunks that do different things. - -=item * - -Uncuddled elses. - -=item * - -No space between function name and its opening parenthesis. - -=item * - -Space after each comma. - -=item * - -Long lines broken after an operator (except "and" and "or"). - -=item * - -Space after last parenthesis matching on current line. - -=item * - -Line up corresponding items vertically. - -=item * - -Omit redundant punctuation as long as clarity doesn't suffer. - -=back - -Larry has his reasons for each of these things, but he doesn't claim that -everyone else's mind works the same as his does. - -Here are some other more substantive style issues to think about: - -=over 4 - -=item * - -Just because you I<CAN> do something a particular way doesn't mean that -you I<SHOULD> do it that way. Perl is designed to give you several -ways to do anything, so consider picking the most readable one. For -instance - - open(FOO,$foo) || die "Can't open $foo: $!"; - -is better than - - die "Can't open $foo: $!" unless open(FOO,$foo); - -because the second way hides the main point of the statement in a -modifier. On the other hand - - print "Starting analysis\n" if $verbose; - -is better than - - $verbose && print "Starting analysis\n"; - -because the main point isn't whether the user typed B<-v> or not. - -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. - -Along the same lines, just because you I<CAN> omit parentheses in many -places doesn't mean that you ought to: - - return print reverse sort num values %array; - return print(reverse(sort num (values(%array)))); - -When in doubt, parenthesize. At the very least it will let some poor -schmuck bounce on the % key in B<vi>. - -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 -parentheses in the wrong place. - -=item * - -Don't go through silly contortions to exit a loop at the top or the -bottom, when Perl provides the C<last> operator so you can exit in -the middle. Just "outdent" it a little to make it more visible: - - LINE: - for (;;) { - statements; - last LINE if $foo; - next LINE if /^#/; - statements; - } - -=item * - -Don't be afraid to use loop labels--they're there to enhance -readability as well as to allow multilevel loop breaks. See the -previous example. - -=item * - -Avoid using grep() (or map()) or `backticks` in a void context, that is, -when you just throw away their return values. Those functions all -have return values, so use them. Otherwise use a foreach() loop or -the system() function instead. - -=item * - -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 C<$]> (C<$PERL_VERSION> in C<English>) to see if it -will be there. The C<Config> module will also let you interrogate values -determined by the B<Configure> program when Perl was installed. - -=item * - -Choose mnemonic identifiers. If you can't remember what mnemonic means, -you've got a problem. - -=item * - -While short identifiers like $gotit are probably ok, use underscores to -separate words. It is generally easier to read $var_names_like_this than -$VarNamesLikeThis, especially for non-native speakers of English. It's -also a simple rule that works consistently with VAR_NAMES_LIKE_THIS. - -Package names are sometimes an exception to this rule. Perl informally -reserves lowercase module names for "pragma" modules like C<integer> and -C<strict>. Other modules should begin with a capital letter and use mixed -case, but probably without underscores due to limitations in primitive -file systems' representations of module names as files that must fit into a -few sparse bytes. - -=item * - -You may find it helpful to use letter case to indicate the scope -or nature of a variable. For example: - - $ALL_CAPS_HERE constants only (beware clashes with perl vars!) - $Some_Caps_Here package-wide global/static - $no_caps_here function scope my() or local() variables - -Function and method names seem to work best as all lowercase. -E.g., $obj-E<gt>as_string(). - -You can use a leading underscore to indicate that a variable or -function should not be used outside the package that defined it. - -=item * - -If you have a really hairy regular expression, use the C</x> 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. - -=item * - -Use the new "and" and "or" operators to avoid having to parenthesize -list operators so much, and to reduce the incidence of punctuation -operators like C<&&> and C<||>. Call your subroutines as if they were -functions or list operators to avoid excessive ampersands and parentheses. - -=item * - -Use here documents instead of repeated print() statements. - -=item * - -Line up corresponding things vertically, especially if it'd be too long -to fit on one line anyway. - - $IDX = $ST_MTIME; - $IDX = $ST_ATIME if $opt_u; - $IDX = $ST_CTIME if $opt_c; - $IDX = $ST_SIZE if $opt_s; - - 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: $!"; - -=item * - -Always check the return codes of system calls. Good error messages should -go to STDERR, include which program caused the problem, what the failed -system call and arguments were, and (VERY IMPORTANT) should contain the -standard system error message for what went wrong. Here's a simple but -sufficient example: - - opendir(D, $dir) or die "can't opendir $dir: $!"; - -=item * - -Line up your transliterations when it makes sense: - - tr [abc] - [xyz]; - -=item * - -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 C<use strict> and C<use warnings> (or B<-w>) in effect -Consider giving away -your code. Consider changing your whole world view. Consider... oh, -never mind. - -=item * - -Be consistent. - -=item * - -Be nice. - -=back |
