Changeset 2398

Timestamp:

Nov 22, 2004, 4:38:16 PM (22 years ago)

Author:

jhoblitt

Message:

break out the examples for foo.pl, Foo.pm, & Foo.pod into separate files
add subsections for $_, filehanldles, & system calls

Location:

trunk/doc/misc

Files:

• Foo.pm (added)
• Foo.pod (added)
• foo.pl (added)
• perlCodeConventions.tex (modified) (8 diffs)

trunk/doc/misc/perlCodeConventions.tex

@@ -1 @@
-%%% $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 +185 @@
 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 +234 @@
 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 +244 @@
 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<import> method and exports no
-    I<symbols>.
-
-    =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<perlgpl> Pod as supplied with Perl 5.8.1 and later.
-
-    =head1 SEE ALSO
-
-    L<Bar::Baz>
-
-    =cut
-\end{verbatim}
-
+\verbatiminput{Foo.pod}
 
 %------------------------------------------------------------------------------
@@ -643 +511 @@
 \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 +1048 @@
 \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 +1099 @@
 
 \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 +1105 @@
 \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}