Index: /trunk/doc/misc/Foo.pm =================================================================== --- /trunk/doc/misc/Foo.pm (revision 2398) +++ /trunk/doc/misc/Foo.pm (revision 2398) @@ -0,0 +1,29 @@ +# Copyright (C) 2004 Joshua Hoblitt +# +# $Id$ + +package Foo; + +use 5.008005; # optional + +use strict; # not optional +use warnings; # not optional + +use base qw( Baz ); # become a subclass of Baz + +use Foo qw( $bar ); # import $bar into our namespace + +use constant MAXFOO => 3; # maximum number of foos + +my $baz; # is a lexical variable in the top level scope + +sub fuu +{ + +} + +1; + +__END__ + +... Index: /trunk/doc/misc/Foo.pod =================================================================== --- /trunk/doc/misc/Foo.pod (revision 2398) +++ /trunk/doc/misc/Foo.pod (revision 2398) @@ -0,0 +1,74 @@ +=pod + +=head1 NAME + +Foo - Does something with Baz. + +=head1 SYNOPSIS + + use Foo; + + ... + +=head1 DESCRIPTION + +More details about what this modules does with Baz. + +=head1 USAGE + +=head2 Import Parameters + +This module accepts no arguments to it's C method and exports no +I. + +=head2 Methods + +=head3 Class Methods + +=over 4 + +=item * methodOne + +details of methodOne + +=item * methodTwo + +details of methodTwo + +... + +=back + +=head1 SUPPORT + +Where to get help. + +=head1 AUTHOR + +Principle authors and contact info. + +=head1 COPYRIGHT + +Copyright (C) 2004 Robert Lupton. All rights reserved. + +This program is free software; you can redistribute it and/or modify it under +the terms of the GNU General Public License as published by the Free Software +Foundation; either version 2 of the License, or (at your option) any later +version. + +This program is distributed in the hope that it will be useful, but WITHOUT ANY +WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A +PARTICULAR PURPOSE. See the GNU General Public License for more details. + +You should have received a copy of the GNU General Public License along with +this program; if not, write to the Free Software Foundation, Inc., 59 Temple +Place - Suite 330, Boston, MA 02111-1307, USA. + +The full text of the license can be found in the LICENSE file included with +this module, or in the L Pod as supplied with Perl 5.8.1 and later. + +=head1 SEE ALSO + +L + +=cut Index: /trunk/doc/misc/foo.pl =================================================================== --- /trunk/doc/misc/foo.pl (revision 2398) +++ /trunk/doc/misc/foo.pl (revision 2398) @@ -0,0 +1,25 @@ +#!/usr/bin/perl + +# Copyright (C) 2004 Joshua Hoblitt +# +# $Id$ + +use 5.008005; # optional + +use strict; # not optional +use warnings; # not optional + +use Foo qw( $bar ); # import $bar into our namespace + +use constant MAXFOO => 3; # maximum number of foos + +my $baz; # is a lexical variable in the top level scope + +sub fuu +{ + +} + +__END__ + +... Index: /trunk/doc/misc/perlCodeConventions.tex =================================================================== --- /trunk/doc/misc/perlCodeConventions.tex (revision 2397) +++ /trunk/doc/misc/perlCodeConventions.tex (revision 2398) @@ -1,3 +1,3 @@ -%%% $Id: perlCodeConventions.tex,v 1.22 2004-11-17 20:51:07 jhoblitt Exp $ +%%% $Id: perlCodeConventions.tex,v 1.23 2004-11-23 02:38:16 jhoblitt Exp $ \documentclass[panstarrs]{panstarrs} @@ -185,32 +185,5 @@ e.g. for file \file{foo.pl}: -\scriptsize -\code{#!/usr/bin/perl}\\ -\\ -\code{# Copyright (C) 2004 Joshua Hoblitt}\\ -\code{#}\\ -\code{# $}\code{Id$}\\ -\normalsize -\begin{verbatim} - use 5.008005; # optional - - use strict; # not optional - use warnings; # not optional - - use Foo qw( $bar ); # import $bar into our namespace - - use constant MAXFOO => 3; # maximum number of foos - - my $baz; # is a lexical variable in the top level scope - - sub fuu - { - - } - - __END__ - - ... -\end{verbatim} +\verbatiminput{foo.pl} \subsubsection{Perl Modules} @@ -261,34 +234,5 @@ e.g. for file \file{Foo.pm}: -\scriptsize -\code{# Copyright (C) 2004 Joshua Hoblitt}\\ -\code{#}\\ -\code{# $}\code{Id$}\\ -\normalsize -\begin{verbatim} - package Foo; - - use 5.008005; # optional - - use strict; # not optional - use warnings; # not optional - - use base qw( Baz ); # become a subclass of Baz - - use Foo qw( $bar ); # import $bar into our namespace - - use constant MAXFOO => 3; # maximum number of foos - - my $baz; # is a lexical variable in the top level scope - - sub fuu - { - - } - - 1; - -__END__ -\end{verbatim} +\verbatiminput{Foo.pm} \subsubsection{Plain Old Documentation} @@ -300,81 +244,5 @@ e.g. for file Foo.pod: -\begin{verbatim} - =pod - - =head1 NAME - - Foo - Does something with Baz. - - =head1 SYNOPSIS - - use Foo; - - ... - - =head1 DESCRIPTION - - More details about what this modules does with Baz. - - =head1 USAGE - - =head2 Import Parameters - - This module accepts no arguments to it's C method and exports no - I. - - =head2 Methods - - =head3 Class Methods - - =over 4 - - =item * methodOne - - details of methodOne - - =item * methodTwo - - details of methodTwo - - ... - - =back - - =head1 SUPPORT - - Where to get help. - - =head1 AUTHOR - - Principle authors and contact info. - - =head1 COPYRIGHT - - Copyright (C) 2004 Robert Lupton. All rights reserved. - - This program is free software; you can redistribute it and/or modify it under - the terms of the GNU General Public License as published by the Free Software - Foundation; either version 2 of the License, or (at your option) any later - version. - - This program is distributed in the hope that it will be useful, but WITHOUT ANY - WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A - PARTICULAR PURPOSE. See the GNU General Public License for more details. - - You should have received a copy of the GNU General Public License along with - this program; if not, write to the Free Software Foundation, Inc., 59 Temple - Place - Suite 330, Boston, MA 02111-1307, USA. - - The full text of the license can be found in the LICENSE file included with - this module, or in the L Pod as supplied with Perl 5.8.1 and later. - - =head1 SEE ALSO - - L - - =cut -\end{verbatim} - +\verbatiminput{Foo.pod} %------------------------------------------------------------------------------ @@ -643,5 +511,5 @@ \subsection{Initialization} -Try to initialize local variables where they're declared. Do not initalize +Try to initialize local variables where they're declared. Do not initialize variables with an empty string or list - this is pointless. @@ -1180,4 +1048,36 @@ \end{verbatim} +\subsection{\$\_} + +Use of the ``default'' variable (\code{$_}) should be avoided. + +\begin{verbatim} + my $foo =~ /(foo.*)/; # Correct + foreach my $foo (@bar) {} # Correct + /(foo.*)/; # AVOID! + $_ = ~/(foo.*)/; # AVOID! +\end{verbatim} + +\subsection{FileHandles} + +Don't use ``bare-words'' as filehandles except for \code{STDIN}, \code{STDOUT}, +or \code{STDERR}. + +\begin{verbatim} + open(STDOUT, '>', $foo) or die "can not open STDOUT: $!"; # Correct + open(my $fh, '>', $foo) or die "can not open file $foo: $!";# Correct + open(FILE , '>', $foo) or die "can not open file $foo: $!"; # AVOID! +\end{verbatim} + +\subsection{System Calls} + +Always check the return code of system calls. + +\begin{verbatim} + open(my $fh, '>', $foo) or die "can not open file $foo: $!"; # Correct + close($fh) or die "can not close file $foo: $!"; # Correct + chdir($foo); # AVOID! +\end{verbatim} + %------------------------------------------------------------------------------ \appendix %Begin Appendices @@ -1199,5 +1099,5 @@ \code{pertidy} is a Perl specific code ``beautifier'' with functionality -similar to \code{indent} or \code{astyle}. It is freely avalible from +similar to \code{indent} or \code{astyle}. It is freely available from \code{http://perltidy.sourceforge.net/}. @@ -1205,5 +1105,5 @@ \file{.perltidyrc} file in your home directory. -Example \file{.perltidyrc} file to acheive the Perl code convention: +Example \file{.perltidyrc} file to achieve the Perl code convention: \verbatiminput{.perltidyrc}