perl 5.000perl-5.000

[editor's note: this commit combines approximate 4 months of furious
releases of Andy Dougherty and Larry Wall - see pod/perlhist.pod for
details.  Andy notes that;
 
Alas neither my "Irwin AccuTrack" nor my DC 600A quarter-inch cartridge 
backup tapes from that era seem to be readable anymore.  I guess 13 years 
exceeds the shelf life for that backup technology :-(.
]

1 files changed, 225 insertions, 0 deletions

diff --git a/pod/perlstyle.pod b/pod/perlstyle.pod
new file mode 100644
index 0000000000..43d53554f9
--- /dev/null
+++ b/pod/perlstyle.pod
@@ -0,0 +1,225 @@
+=head1 NAME
+
+perlstyle - Perl style guide
+
+=head1 DESCRIPTION
+
+=head2 Style
+
+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.  
+
+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:
+
+=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 multiline 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 paren.
+
+=item *
+
+Space after each comma.
+
+=item *
+
+Long lines broken after an operator (except "and" and "or").
+
+=item *
+
+Space after last paren 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 doen'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";
+
+since 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
+parens 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 multi-level loop breaks.  See the
+previous example.
+
+=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<$]> ($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 *
+
+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 punctuational
+operators like C<&&> and C<||>.  Call your subroutines as if they were
+functions or list operators to avoid excessive ampersands and parens.
+
+=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 *
+
+Line up your translations 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 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
+