Index: /trunk/doc/misc/perlCodeConventions.tex
===================================================================
--- /trunk/doc/misc/perlCodeConventions.tex	(revision 3089)
+++ /trunk/doc/misc/perlCodeConventions.tex	(revision 3090)
@@ -1,3 +1,3 @@
-%%% $Id: perlCodeConventions.tex,v 1.44 2005-01-18 23:25:08 jhoblitt Exp $
+%%% $Id: perlCodeConventions.tex,v 1.45 2005-01-25 21:44:01 jhoblitt Exp $
 \documentclass[panstarrs]{panstarrs}
 
@@ -13,5 +13,5 @@
 \project{Pan-STARRS Image Processing Pipeline}
 \organization{Institute for Astronomy}
-\version{DR01}
+\version{DR02}
 \docnumber{PSDC-430-010}
 
@@ -26,4 +26,6 @@
 \hline
 DR01& 2004-12-01 & Second Draft\\
+\hline
+DR02& 2005-01-24 & Third Draft\\
 \RevisionsEnd
 
@@ -54,6 +56,7 @@
 This document is derived from the Pan-STARRS IPP C Code Standards document
 (PSDC 430-004), which is derived from the Sun Microsystems Java language coding
-standards presented in the Java Language Specification\footnote{The Java
-Language Specification - http://java.sun.com/docs/books/jls/index.html}.
+standards presented in the \emph{Java Language Specification}\footnote{The
+Java Language Specification -
+\code{http://java.sun.com/docs/books/jls/index.html}}.
 
 \begin{verbatim}
@@ -64,6 +67,6 @@
 \end{verbatim}
 
-See the Java Code Conventions Web site
-(\code{http://java.sun.com/docs/codeconv/}) for more details.
+See the \emph{Java Code Conventions} web site\footnote{The Java Code
+Conventions - \code{http://java.sun.com/docs/codeconv/}} for more details.
 
 Such an adaption is explicitly permitted by the Sun Microsystems
@@ -79,15 +82,18 @@
 common with Perl programmers.  Instead, it is an attempt to make the C and Perl
 coding styles as consistent as is reasonably feasible within the Pan-STARRS
-project.  This document contains only a brief discussion of Perl's
-Object-Oriented features and none of it's more advanced features.
+project.  Further limiting the possible applicability of this document, only
+language features that are deemed likely to be used by the Pan-STARRS project
+are discussed.  This has resulted in only a brief discussion of Perl's
+Object-Oriented features and none of it's more advanced features (e.g.
+AUTOLOAD).
 
 \subsection{Applicability}
 
-This document is intended to be relevant to Perl 5.8.0 or later.
+This document is intended to be relevant to Perl5, version 5.8.0 or later.
 
 \subsection{Conformance}
 
 If any of the conventions established in this document conflict with source
-code that has been formated by \code{perltidy} (see \S\ref{perltidy}), the
+code that has been formatted by \code{perltidy} (see \S\ref{perltidy}), the
 formatting as output by \code{perltidy} will be considered to be in compliance
 with the Perl Code Standards.
@@ -109,5 +115,5 @@
 \subsection{File Suffixes}
 
-Software uses the following file suffixes:
+Software uses the following file suffixes (in lowercase):
 \begin{center}
 \begin{tabular}{ll}
@@ -130,6 +136,7 @@
 The preferred name for a file that invokes a ``build'' process.  Typically this
 calls \code{ExtUtils::MakeMaker} or \code{Module::Build} setup the the
-necessary files to build and install a module or compile Swig generated C
-code.\\
+necessary files to build and install a module or compile Swig generated C code.
+\emph{The capitalized \code{.PL} suffix is reserved for build and configuration
+scripts}\\
 \end{tabular}
 \end{center}
@@ -152,5 +159,5 @@
 \item
 For an example of a properly formatted program, see
-Complete Program Example (\S\ref{SourceExample}).
+\emph{Complete Program Example} (\S\ref{SourceExample}).
 
 \item
@@ -164,9 +171,9 @@
 \subsubsection{Perl Scripts}
 
-Script files should have the following order:
+Script files should have, in the following order:
 
 \begin{itemize}
 \item 
-A Bourne shell ``she-bang'' for \code{perl}.  \code{#!/usr/bin/perl}.
+A Bourne shell ``she-bang'' for \code{perl}.  e.g.  \code{#!/usr/bin/perl}.
 
 \item 
@@ -194,5 +201,9 @@
 
 \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
+The functional ``body'' of the script.  This where command line parameter
+parsing, subroutine calls, etc. are placed.
 
 \item 
@@ -207,10 +218,10 @@
 \end{itemize}
 
-For an example of a properly organized script, see Script File Example
+For an example of a properly organized script, see \emph{Script File Example}
 (\S\ref{foo.pl}).
 
 \subsubsection{Perl Modules}
 
-Module files should have the following order:
+Module files should have, in the following order:
 
 \begin{itemize}
@@ -262,5 +273,5 @@
 \end{itemize}
 
-For an example of a properly organized module, see Module File Example
+For an example of a properly organized module, see \emph{Module File Example}
 (\S\ref{Foo.pm}).
 
@@ -308,5 +319,5 @@
 \end{itemize}
 
-For an example of a properly organized Pod, see Pod File Example
+For an example of a properly organized Pod, see \emph{Pod File Example}
 (\S\ref{Foo.pod}).
 
@@ -345,6 +356,6 @@
 \item Prefer higher-level breaks to lower-level breaks.
 
-\item Indent new lines 4 spaces deeper than the nesting depth of the line on
-which the expression began.
+\item Indent new lines 1 indentation unit deeper than the nesting depth of the
+line on which the expression began.
 
 \item If it is convenient to list one statement per line (similar to a hash
@@ -378,5 +389,8 @@
 \end{verbatim}
 
-Here are three acceptable ways to format ternary expressions:
+Below are three acceptable ways to format ternary expressions.
+\emph{Expression fragments should be indented such that \code{?} and \code{:}
+are aligned vertically (as opposed to being indented a fixed number of
+indentation units).}
 
 \begin{verbatim}
@@ -399,5 +413,5 @@
 
 Comments should not be used to comment out large sections of code.  When
-deactivating 2 or fewer consecutive lines of code a double hash (\code{##})
+deactivating 3 or fewer consecutive lines of code a double hash (\code{##})
 should be used at the very beginning of the line(s).
 
@@ -410,5 +424,5 @@
 \end{verbatim}
 
-When deactivating 3 or more lines of code an embedded Pod statement should be
+When deactivating 4 or more lines of code an embedded Pod statement should be
 used.  The opening statement should be \code{=for off} and the closing
 statement should be \code{=cut}.  The deactivated section should remain nested
@@ -478,5 +492,5 @@
 \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
+    # lines, then has a logical separation before another comment
     #
     # this is an adjoined comment
@@ -491,5 +505,5 @@
 separated from the closing semi-colon by a single space.
 
-Here's an example of a trailing comment in Perl code: 
+Here's an example trailing comments:
 
 \begin{verbatim}
@@ -512,10 +526,10 @@
 
 Plain Old Documentation format or Pod will be used to produce documentation of
-the subroutines and variables in the exposed API.  See Plain Old Documentation
-(\S\ref{pod}).
-
-If you need to give information about a interface, or variable that isn't
+the subroutines and variables in the exposed API.  See \emph{Plain Old
+Documentation} (\S\ref{pod}).
+
+If you need to give information about an interface, or variable that isn't
 appropriate for Podification, use a normal implementation single-line or
-multi-line comment immediately \textit{before} the code (as exampled above).
+multi-line comment immediately \emph{before} the code (as exampled above).
 
 
@@ -536,5 +550,5 @@
 
 \begin{verbatim}
-    my ($level, $size);
+    my ($level, $size);                     # AVOID!
 \end{verbatim}
 
@@ -588,5 +602,6 @@
 \end{verbatim}
 
-Consider using the \code{qw} operator when assigning strings to an array.
+Consider using the \code{qw} operator to avoid repetitive string quoting when
+assigning to an array.
 
 \begin{verbatim}
@@ -643,9 +658,10 @@
 \end{verbatim}
 
-\emph{This restriction does not apply to Perl's built in variables.}
+\emph{This restriction does not apply to Perl's built-in variables or the
+package variable used by some modules to control global behavior.}
 
 \subsection{Package Variables}
 
-See When to Make Symbols Global (\S\ref{globals}).
+See \emph{When to Make Symbols Global} (\S\ref{globals}).
 
 \subsection{Initialization}
@@ -658,5 +674,5 @@
 
 \item
-Do not initialize variables with an empty string or list - this is pointless.
+Do not initialize variables with an empty string or list; this is pointless.
 
 \item
@@ -675,4 +691,8 @@
 This allows them to be initialized as they are created, and naturally
 associates their declaration with their use.
+
+Practical examples of when \emph{not} to place variable declarations at the top
+of a block include loop iterators, intermediate value variables, and
+variables used for returning values from nested scopes.
 
 \subsection{Subroutine Declarations}
@@ -752,4 +772,62 @@
 where the two actions are intimately related.
 
+\subsubsection{return Statements}
+
+A \code{return} statement should not use parentheses unless they make the
+return value more obvious in some way.  All subroutines must have an explicit,
+non-null, return statement unless they are returning an error condition, in
+which case a bare \code{return} is acceptable.   Example:
+
+\begin{verbatim}
+    return $a;                              # Correct
+    return;                                 # Correct only if indicating an error
+    return $myDisk->size;                   # Correct
+    return ($size ? $size : $defaultSize);  # Correct
+    return($a);                             # AVOID!
+    return ($a);                            # AVOID!
+\end{verbatim}
+
+\emph{In the absence of an explicit return statement Perl will return the
+results of the last statement executed.  Relying on this behavior is likely to
+confuse maintenance programmers and therefore should be avoided.}
+
+Try to make the structure of your program match the intent. Example:
+
+\begin{verbatim}
+    if (booleanExpression) {
+        return true;
+    } else {
+        return false;
+    }
+\end{verbatim}
+
+should instead be written as
+
+\begin{verbatim}
+    return booleanExpression;
+\end{verbatim}
+
+If you're concerned that the reader may not know that \code{booleanExpression}
+is boolean, use:
+
+\begin{verbatim}
+    return (booleanExpression ? true : false);
+\end{verbatim}
+
+Similarly,
+
+\begin{verbatim}
+    if (condition) {
+        return $x;
+    }
+    return $y;
+\end{verbatim}
+
+should be written as
+
+\begin{verbatim}
+    return (condition ? x : y);
+\end{verbatim}
+
 \subsection{Compound Statements}
 
@@ -765,26 +843,5 @@
 \end{itemize}
 
-\subsection{return Statements}
-
-A \code{return} statement with a value should not use parentheses unless they
-make the return value more obvious in some way.  All subroutines must have an
-explicit, non-null, return statement.   Example:
-
-\begin{verbatim}
-    return undef;                           # Correct
-    return;                                 # AVOID!
-    return $myDisk->size;                   # Correct
-    return ($size ? $size : $defaultSize);  # Correct
-\end{verbatim}
-
-\emph{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 parentheses \code{()} around conditionals.
+\subsubsection{if, if-else, if-elsif-else Statements}
 
 The \code{if-else} class of statements should have the following form:
@@ -810,5 +867,8 @@
 \end{verbatim}
 
-\subsection{C style for Statements}
+\emph{The same formatting applies to \code{unless}, \code{unless-else}, \&
+\code{unless-elsif-else} statements.}
+
+\subsubsection{C style for Statements}
 
 A \code{for} statement should have the following form:
@@ -829,5 +889,5 @@
 
 An empty \code{for} statement (one in which all the work is done in the
-initialization, condition, and update clauses) should have the following forms:
+initialization, condition, and update clauses) should have the following form:
 
 \begin{verbatim}
@@ -841,5 +901,7 @@
 the loop (for the update clause).
 
-\subsection{Perl style for, foreach Statements}
+\emph{Generally, ``Perlish'' style loops are preferred over the C form.}
+
+\subsubsection{Perl style for, foreach Statements}
 
 A Perlish \code{for} or \code{foreach} statement should have the following
@@ -848,10 +910,16 @@
 \begin{verbatim}
     foreach my $item (@workingList) {
-        # do stuff with $item
+        statements;
+    }
+
+    foreach my $item (@workingList) {
+        statements;
+    } continue {
+        statements;
     }
 \end{verbatim}
 
 The current working item should be interacted with through a declared lexical
-variable and  not via \code{$_}.
+variable and not via \code{$_}.
 
 \begin{verbatim}
@@ -861,5 +929,5 @@
 \end{verbatim}
 
-\subsection{while Statements}
+\subsubsection{while Statements}
 
 A \code{while} statement should have the following form:
@@ -869,4 +937,20 @@
         statements;
     }
+
+    while (condition) {
+        statements;
+    } continue {
+        statements;
+    }
+\end{verbatim}
+
+Do \emph{not} use \code{$_} when iterating through a filehandle.  Instead, place
+each ``line'' of the filehandle into a named lexical variable.
+
+\begin{verbatim}
+    my $line;
+    while (defined($line = <FILE>)) {
+        statements;
+    }
 \end{verbatim}
 
@@ -877,18 +961,23 @@
 \end{verbatim}
 
-\subsection{do-while Statements}
-
-A \code{do-while} statement should have the following form:
+\emph{Consider using the \code{map} subroutine instead of a loop for list
+generation.}
+
+\subsubsection{do Statements}
+
+In Perl \code{do} is a built-in subroutine.  Traditional \code{do-while} like
+statements may be constructed with it by using Statement Modifiers (see
+\S\ref{statement-modifiers}) in the following form:
 
 \begin{verbatim}
     do {
         statements;
-    } while (condition);
-\end{verbatim}
-
-\subsection{Label Statements}
-
-Code labels should be indented to align with the previous level of
-indentation.
+    } statement-modifier (condition);
+\end{verbatim}
+
+\subsubsection{Label Statements}
+
+Code labels should be indented to align with the previous level of indentation.
+Do \emph{not} label a loop unless you are going to use the label.
 
 \begin{verbatim}
@@ -900,7 +989,7 @@
 \end{verbatim}
 
-\subsection{Blocks}
-
-The contense of a block should be idented one level.
+\subsubsection{Blocks}
+
+The contents of a block should be indented one level.
 
 \begin{verbatim}
@@ -912,8 +1001,34 @@
 \end{verbatim}
 
+\subsection{Statement Modifiers}
+\label{statement-modifiers}
+
+These keywords are considered acceptable for use as ``Statement Modifiers'':
+\code{if}, \code{unless} \& \code{until}.  These keywords should generally be
+avoided for that purpose: \code{while} \& \code{foreach}.
+
+Statement Modifiers should only be used \emph{only} when it makes the intent
+for the code more obvious.  e.g.
+
+\begin{verbatim}
+    die "you forgot to handle some case" unless $flag;  # Correct
+    $a = 1 if (($b == $c) && defined($d);               # AVOID!
+\end{verbatim}
+
+Parenthesis should be used with complex expressions.
+
+\begin{verbatim}
+    someSubCall($a, $b, $c) if ($foo eq 'bar' || $baz > 10);    # Correct
+    someSubCall($a, $b, $c) if $foo eq 'bar' || $baz > 10;      # AVOID!
+\end{verbatim}
+
 
 %------------------------------------------------------------------------------
 
 \section{White Space}
+
+In general, be very liberal in the use of whitespace, both horizontal and
+vertical, if it will improve the clarity and readability of your code.
+
 \subsection{Blank Lines}
 
@@ -921,9 +1036,5 @@
 are logically related.
 
-Two blank lines should always be used in the following circumstances:
-\begin{itemize}
-\item
-Between sections of a source file
-\end{itemize}
+Two blank lines should always be used between sections of a source file.
 
 One blank line should always be used in the following circumstances:
@@ -992,5 +1103,5 @@
 \end{itemize}
 
-Blank spaces should \textit{not} be used in the following circumstances:
+Blank spaces should \emph{not} be used in the following circumstances:
 
 \begin{itemize}
@@ -1027,5 +1138,5 @@
 
 The filenames of all scripts should be verbal phrases, in mixed case.  The
-capitalized \code{.PL} suffix is reserved for ``build'' scripts.
+capitalized \code{.PL} suffix is reserved for build and configuration scripts.
 
 &
@@ -1083,5 +1194,5 @@
 of a variable name should be mnemonic- that is, designed to indicate to the
 casual observer the intent of its use. One-character variable names should be
-avoided except for temporary \textit{throwaway} variables. Common names for
+avoided except for temporary \emph{throwaway} variables. Common names for
 temporary variables are \code{$i}, \code{$j}, \code{$k}, \code{$m}, and \code{$n}
 for integers; \code{$c}, \code{$d}, and \code{$e} for characters.
@@ -1238,44 +1349,4 @@
 \end{verbatim}
 
-\subsubsection{Returning Values}
-
-Try to make the structure of your program match the intent. Example:
-
-\begin{verbatim}
-    if (booleanExpression) {
-        return true;
-    } else {
-        return false;
-    }
-\end{verbatim}
-
-should instead be written as
-
-\begin{verbatim}
-    return booleanExpression;
-\end{verbatim}
-
-If you're concerned that the reader may not know that \code{booleanExpression}
-is boolean, use:
-
-\begin{verbatim}
-    return (booleanExpression ? true : false);
-\end{verbatim}
-
-Similarly,
-
-\begin{verbatim}
-    if (condition) {
-        return $x;
-    }
-    return $y;
-\end{verbatim}
-
-should be written as
-
-\begin{verbatim}
-    return (condition ? x : y);
-\end{verbatim}
-
 \subsubsection{Expressions before `?' in the Conditional Operator }
 
@@ -1298,5 +1369,5 @@
 \end{verbatim}
 
-\subsubsection{FileHandles}
+\subsubsection{Filehandles}
 
 Do not use ``bare-words'' as filehandles except for \code{STDIN}, \code{STDOUT},
@@ -1383,5 +1454,5 @@
 \subsubsection{Inheritance}
 
-Do not use the \code{@ISA} package variable for subclassing.  Instead, use the
+Do not use the \code{@ISA} package variable for sub-classing.  Instead, use the
 \code{base} pragma.
 
@@ -1439,11 +1510,10 @@
 
 \item
-Consider using the \code{q} and \code{qq} operators instead of backslashes
-(\code{\}) when quoting strings that contain other quotes or blackslases.
+ Consider using the \code{q} and \code{qq} operators instead of backslashes
+(\code{\}) when quoting strings that contain other quotes or backslashes.
 
 \item
 Consider using the \code{quotemeta} subroutine when handling strings that
-contain meta-characters.
-\end{itemize}
+contain meta-characters.  \end{itemize}
 
 \subsubsection{String Concatenation}
@@ -1483,5 +1553,6 @@
 
 \begin{verbatim}
-    sub myopen (*;$)                    # AVOID!
+    sub myopen (*;$);                   # AVOID!
+    sub myopen (*;$) { }                # AVOID!
 \end{verbatim}
 
@@ -1543,5 +1614,5 @@
 http://search.cpan.org/~drolsky/Params-Validate/} is a Perl module that allows
 you to perform rigorous subroutine parameter validation.  It is highly
-configurable and validation may be deactivated at runtime
+configurable and validation may be deactivated at runtime.
 
 The basic premise is that a validation specification is passed to one of