Index: trunk/doc/misc/perlCodeConventions.tex
===================================================================
--- trunk/doc/misc/perlCodeConventions.tex	(revision 2363)
+++ trunk/doc/misc/perlCodeConventions.tex	(revision 2373)
@@ -1,3 +1,3 @@
-%%% $Id: perlCodeConventions.tex,v 1.15 2004-11-13 03:39:25 jhoblitt Exp $
+%%% $Id: perlCodeConventions.tex,v 1.16 2004-11-16 04:58:16 jhoblitt Exp $
 \documentclass[panstarrs]{panstarrs}
 
@@ -69,5 +69,5 @@
 Although Perl's syntax is similar to that of C or Java, there are many
 signification deviations.  This has lead to a coding style within the Perl
-community that is generally significantly different then that used for C or
+community that is generally significantly different than that used for C or
 Java (See the \code{perlstyle} Pod in the standard Perl documentation for an
 example of this).  This document does not attempt to define the coding style
@@ -86,5 +86,5 @@
 complaints it may generate.
 
-\code{rhl@astro.princeton.edu}.
+\code{<rhl@astro.princeton.edu>}.
 
 %------------------------------------------------------------------------------
@@ -101,7 +101,7 @@
 \textbf{File Type}& \textbf{Suffix}\\
 \hline
-Perl scripts&       \code{.pl}\\
-Perl modules&       \code{.pm}\\
-Perl documentation& \code{.pod}\\
+Perl scripts&               \code{.pl}\\
+Perl modules&               \code{.pm}\\
+Plain old documentation&    \code{.pod}\\
 \end{tabular}
 \end{center}
@@ -133,4 +133,8 @@
 Source File Example (\S\ref{SourceExample}).
 
+``Scripts'' have user documentation included at the end of the file.
+
+``Modules'' have documentation included in a companion \code{.pod}.
+
 \subsection{Source Files}
 
@@ -186,14 +190,14 @@
 \normalsize
 \begin{verbatim}
-use 5.008005;   # optional
-
-use strict;     # not optional
-use warnings;   # not optional
-
-use Foo qw( $bar );
-
-use constant MAXFOO => 3;
-
-my $baz;
+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
@@ -236,5 +240,6 @@
 
 \item 
-Any script level "globals" declared as lexical variables.  E.g. \code{my $foo}
+Any script level ``globals'' declared as lexical variables.  E.g. \code{my
+$foo}
 
 \item 
@@ -248,7 +253,4 @@
 A \code{__END__} token to instruct the perl parser to stop looking for
 executable code.
-
-\item
-Any Pod documentation about the module.
 \end{itemize}
 
@@ -263,16 +265,16 @@
 package Foo;
 
-use 5.008005;   # optional
-
-use strict;     # not optional
-use warnings;   # not optional
-
-use base qw( Baz );
-
-use Foo qw( $bar );
-
-use constant MAXFOO => 3;
-
-my $baz;
+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
@@ -284,14 +286,11 @@
 
 __END__
-
-...
-\end{verbatim}
-
-\subsubsection{Perl Documentation}
-
-In most cases documentation should be included as ether in-line Pod or after
-the \code{__END__} token in a \code{.pl} file.  The format for documentation
-embedded in a \code{.pl} file after the \code{__END__} token or as a stand
-alone file is as follows:
+\end{verbatim}
+
+\subsubsection{Plain Old Documentation}
+
+This is the format for documentation in a \code{.pl} file after the
+\code{__END__} token and the \code{.pod} file that should accompany a
+a module (\code{.pm}).
 
 e.g. for file Foo.pod:
@@ -412,5 +411,5 @@
 \item Align the new line with the beginning of the expression at the
 same level on the previous line\footnote{For emacs users, this means
-the indentation that \code{<tab>} produces}.
+the indentation that \code{<tab>} generally produces}.
 
 \item If the above rules lead to confusing code or to code that's
@@ -432,11 +431,12 @@
 \end{verbatim}
 
-Following are two examples of breaking an arithmetic expression. The
-first is preferred, since the break occurs outside the parenthesized
-expression, which is at a higher level.
+Following are two examples of breaking an arithmetic expression. The first is
+preferred, since the break occurs outside the parenthesized expression, which
+is at a higher level.  The second is demonstrating a statement being broken at
+too low a level.
 
 \begin{verbatim}
     $longName1 = $longName2*($longName3 + $longName4 - $longName5) +
-        4*$longname6;                    # PREFER
+        4*$longname6;                   # PREFER
     
     $longName1 = $longName2*($longName3 + $longName4 -
@@ -445,4 +445,5 @@
 
 Here are three acceptable ways to format ternary expressions:
+
 \begin{verbatim}
 $alpha = (aLongBooleanExpression) ? $beta : $gamma;  
@@ -506,6 +507,6 @@
 code to make it clearer.
 
-Comments should not be enclosed in large boxes drawn with asterisks or
-other characters.
+Comments should not be enclosed in large boxes drawn with hashes or other
+characters.
 \hfil\break
 Comments should never include special characters such as form-feed and
@@ -531,5 +532,13 @@
 \subsubsection{Multi-Line Comments}
 
-Merely a repetition of single-line comments.
+Merely a repetition of single-line comments.  Logically distinct but adjoining
+comments should be separated by an empty comment line.
+
+\begin{verbatim}
+# this is the start of a multi-line comment that continues across a couple of
+# lines then has a logical separation before another comment
+#
+# this is an adjoined comment
+\end{verbatim}
 
 \subsubsection{Trailing Comments}
@@ -607,5 +616,5 @@
 Do not put different types on the same line. Example:
 \begin{verbatim}
-my ($foo, @fooArray);                  # WRONG!
+my ($foo, @fooArray);                  # AVOID!
 \end{verbatim}
 
@@ -621,5 +630,5 @@
 sub mySubroutine
 {
-    local $count;
+    local $count;                       # AVOID!
     ...
 }
@@ -664,10 +673,13 @@
 
 \item
-Closing brace \CODE.}. starts a line by itself indented to match its
-corresponding opening statement, except when it is a null statement the
-\CODE.}. should appear immediately after the \CODE.{..
+Closing brace \CODE.}. starts a line by itself, except when it is a null
+statement the \CODE.}. should appear immediately after the \CODE.{..
 
 \item
 The last line before the closing brace must explicitly declare a return value.
+
+\item
+
+Do not nest named subroutines.
 \end{itemize}
 
@@ -695,5 +707,5 @@
 \end{verbatim}
 
-An example of a reasonably two-statement line is:
+An example of a reasonable two-statement line is:
 \begin{verbatim}
 $foo++; $bar--;
@@ -713,10 +725,4 @@
 indented to the beginning of the compound statement.
 
-\item Braces are used around all statements, even single statements,
-when they are part of a control structure, such as a \code{if-else} or
-\code{for} statement. This makes it easier to add statements without
-accidentally introducing bugs due to forgetting to add braces.
-\end{itemize}
-
 \subsection{return Statements}
 
@@ -734,11 +740,13 @@
 \end{verbatim}
 
-Note:  In absence of an explicit return statement Perl will return the results
-of the last statement executed.  A null \code{return} statement causes the
-result of the last statement executed to be returned.
-
-\subsection{if, if-else, if elsif else Statements}
-
-\code{if} statements must always use braces \{\} around statements and parenthesis
+Note:  In the absence of an explicit return statement Perl will return the
+results of the last statement executed.  A null \code{return} statement also
+causes the result of the last statement executed to be returned.  Relying on
+this behavior is likely to confuse maintenance programmers and therefore should
+be avoided.
+
+\subsection{if, if-else, if-elsif-else Statements}
+
+\code{if} statements must always use braces \{\} around statements and parentheses
 () around conditionals.
 
@@ -777,5 +785,5 @@
 
 \begin{verbatim}
-for (my $i =0; $i < 100; $i++) {
+for (my $i = 0; $i < 100; $i++) {
     print "$i\n";
 }
@@ -841,5 +849,5 @@
 \end{verbatim}
 
-\subsection{label Statements}
+\subsection{Label Statements}
 
 Code labels should be indented to align with the previous level of
@@ -983,5 +991,5 @@
 
 Constant names should be in all capital letters and highly descriptive.  The
-\code{constant} pragma should be used to declare constants.  Note: 'constants'
+\code{constant} pragma should be used to declare constants.  Note: `constants'
 created this way can not be interpolated inside of double quoted strings.
 
@@ -989,5 +997,5 @@
 \code{use constant PI => 3.14159265;}\hfil\break
 \code{use constant LENGTHS => qw(2, 4, 8);}\hfil\break
-\code{use constant CLASSES => (raw => 1, processed => 2);}\hfil\break
+\code{use constant CLASSES => (a => 1, b => 2);}\hfil\break
 
 \\
@@ -1000,7 +1008,7 @@
 &
 
-\code{package Class::Data::Inheritable;}\hfil\break
-\code{package Time::HiRes;}\hfil\break
-\code{package XML::SimpleObject;}\hfil\break
+\code{package PS::Metadata;}\hfil\break
+\code{package PS::Modules::Debias;}\hfil\break
+\code{package PS::Modules::FlatField;}\hfil\break
 
 \\
@@ -1009,5 +1017,5 @@
 
 Label names should be in all capital letters and short.  Generally they should
-attempt to describe the 'thing' being operated on by the loop they are labeling.
+attempt to describe the `thing' being operated on by the loop they are labeling.
 
 &
@@ -1098,6 +1106,6 @@
 
 \begin{verbatim}
-if ($a & $b || $c & $d)                 # AVOID!
-if (($a & $b) || ($c & $d))             # RIGHT
+if ($a & $b || $c & $d) {}              # AVOID!
+if (($a & $b) || ($c & $d)) {}          # RIGHT
 \end{verbatim}
 
@@ -1107,5 +1115,5 @@
 
 \begin{verbatim}
-if (($a == $b && $c == $d) || $e == $f)
+if (($a == $b && $c == $d) || $e == $f) {}
 $l << ($j + $k)
 ($l << $j) + $k