Index: trunk/doc/misc/perlCodeConventions.tex
===================================================================
--- trunk/doc/misc/perlCodeConventions.tex	(revision 2356)
+++ trunk/doc/misc/perlCodeConventions.tex	(revision 2359)
@@ -1,3 +1,3 @@
-%%% $Id: perlCodeConventions.tex,v 1.10 2004-11-12 22:31:58 jhoblitt Exp $
+%%% $Id: perlCodeConventions.tex,v 1.11 2004-11-13 02:57:30 jhoblitt Exp $
 \documentclass[panstarrs]{panstarrs}
 
@@ -30,4 +30,5 @@
 %%% References here.
 \textbf{\PS{} ID} & \textbf{Title} & \textbf{Author} \\
+\hline
 430-004 &Pan-STARRS IPP C Code Standards    &Robert Lupton\\
 \hline
@@ -66,6 +67,6 @@
 \subsection{Limitations}
 
-Although Perl's syntax is in many ways similar to that of C or Java, there are
-many signification deviations.  This has lead to a coding style within the Perl
+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
 Java (See the \code{perlstyle} Pod in the standard Perl documentation for an
@@ -73,5 +74,10 @@
 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.
+project.  This document also only contains brief discussion of Perl's
+Object-Oriented features and none of Perl's more advanced features.
+
+\subsection{Applicability}
+
+This document is intended to be relevant with Perl 5.8.0 or later.
 
 \subsection{To whom should I Complain?}
@@ -131,12 +137,87 @@
 \subsubsection{Perl Scripts}
 
-Include files should have the following order:
+Script files should have the following order:
 
 \begin{itemize}
 \item 
 A Bourne shell "she-bang" for perl.  \code{#!/usr/bin/perl}.
+
 \item 
 A Copyright notice followed by a blank commented line.  Then one commented line
 per CVS keyword to be expanded.
+
+\item
+A minimum perl version requirement in long form (vStrings are not allowed).
+Where \code(requirement = revision + version / 1000 + subversion /
+1\_000\_000).  E.g. A minimum requirement of Perl 5.8.5 would be expressed as
+\code{use 5.008005}
+
+\item 
+A \code{use strict} and \code{use warnings} declaration.
+
+\item 
+Any base classes.
+
+\item 
+Any constant declarations. 
+
+\item 
+Any script level "globals" declared as lexical variables.  E.g. \code{my $foo}
+
+\item 
+Any subroutines.
+
+\item
+A \code{__END__} token to instruct the perl parser to stop looking for
+executable code.
+
+\item
+Any Pod documentation about the script.
+\end{itemize}
+
+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 );
+
+use constant MAXFOO => 3;
+
+my $baz;
+
+sub fuu
+{
+
+}
+
+__END__
+
+...
+\end{verbatim}
+
+\subsubsection{Perl Modules}
+
+Perl Module/Namespaces deviate slightly from the standard naming conventions in
+that the first character is always capitalized.
+
+\begin{itemize}
+\item 
+A Copyright notice followed by a blank commented line.  Then one commented line
+per CVS keyword to be expanded.
+
+\item
+A Perl \code{package} declaration.
+
 \item
 A minimum perl version requirement in long form (vStrings are not allowed).
@@ -144,26 +225,41 @@
 E.g. A minimum requirement of Perl 5.8.5 would be expressed as \code{use
 5.008005}
+
 \item 
 A \code{use strict} and \code{use warnings} declaration.
+
 \item 
 Any modules to include. 
+
+\item 
+Any constant declarations. 
+
 \item 
 Any script level "globals" declared as lexical variables.  E.g. \code{my $foo}
+
 \item 
 Any subroutines.
+
+\item
+A \code{1} on a line by itself so when the module is parsed it always ends with
+a true expression.
+
 \item
 A \code{__END__} token to instruct the perl parser to stop looking for
 executable code.
-\item Any Pod documentation about the script.
+
+\item
+Any Pod documentation about the module.
 \end{itemize}
 
-e.g. for file \file{foo.pl}:
-
-\begin{verbatim}
-#!/usr/bin/perl
-
-# Copyright (C) 2004  Joshua Hoblitt
-#
-# $Id: perlCodeConventions.tex,v 1.10 2004-11-12 22:31:58 jhoblitt Exp $
+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
@@ -172,5 +268,9 @@
 use warnings;   # not optional
 
+use base qw( Baz );
+
 use Foo qw( $bar );
+
+use constant MAXFOO => 3;
 
 my $baz;
@@ -181,66 +281,9 @@
 }
 
+1;
+
 __END__
-\end{verbatim}
-
-\subsubsection{Perl Modules}
-
-Perl module names deviate slightly from the other naming conventions in that
-the first character is always capitalized.
-
-\begin{itemize}
-\item 
-A Copyright notice followed by a blank commented line.  Then one commented line
-per CVS keyword to be expanded.
-\item
-A Perl Package declaration.  \code{package Foo}
-\item
-A minimum perl version requirement in long form (vStrings are not allowed).
-Where \code(requirement = revision + version / 1000 + subversion / 1\_000\_000).
-E.g. A minimum requirement of Perl 5.8.5 would be expressed as \code{use
-5.008005}
-\item 
-A \code{use strict} and \code{use warnings} declaration.
-\item 
-Any modules to include. 
-\item 
-Any script level "globals" declared as lexical variables.  E.g. \code{my $foo}
-\item 
-Any subroutines.
-\item
-A \code{1} on a line by itself so when the module is parsed it always ends with
-a true expression.
-\item
-A \code{__END__} token to instruct the perl parser to stop looking for
-executable code.
-\item Any Pod documentation about the module.
-\end{itemize}
-
-e.g. for file \file{Foo.pm}:
-
-\begin{verbatim}
-# Copyright (C) 2004  Joshua Hoblitt
-#
-# $Id: perlCodeConventions.tex,v 1.10 2004-11-12 22:31:58 jhoblitt Exp $
-
-package Foo;
-
-use 5.008005;   # optional
-
-use strict;     # not optional
-use warnings;   # not optional
-
-use Foo qw( $bar );
-
-my $baz;
-
-sub fuu
-{
-
-}
-
-1;
-
-__END__
+
+...
 \end{verbatim}
 
@@ -328,4 +371,5 @@
 =cut
 \end{verbatim}
+
 
 %------------------------------------------------------------------------------
@@ -410,4 +454,5 @@
 \end{verbatim}
 
+
 %------------------------------------------------------------------------------
 
@@ -421,4 +466,5 @@
 
 Example of deactivating a single line code.
+
 \begin{verbatim}
     if ($foo) {
@@ -432,4 +478,5 @@
 
 Example of deactivating multiple lines of code.
+
 \begin{verbatim}
 if (0) {
@@ -475,4 +522,5 @@
 
 Example of a single-line comment.
+
 \begin{verbatim}
 # some words
@@ -486,11 +534,11 @@
 \label{col41} 
 
-Very short comments can appear on the same line as the code they
-describe, and should be indented to column 41\footnote{In emacs, this
-may be achieved with \code{ESC;}}. If the code extends beyond this
-column, the comment should be separated from the closing semi-colon by
-a single space.
+Very short comments can appear on the same line as the code they describe, and
+should be indented to column 41\footnote{In emacs, this may be achieved with
+\code{ESC;}}. If the code extends beyond this column, the comment should be
+separated from the closing semi-colon by a single space.
 
 Here's an example of a trailing comment in Perl code: 
+
 \begin{verbatim}
 if ($a == 2) {
@@ -532,15 +580,12 @@
 multi-line comment  immediately \textit{before} the code (as exampled above).
 
+
 %------------------------------------------------------------------------------
 
 \section{Declarations}
 
-All globally-visible symbols must be declared in a suitable header
-(.h) file.  Global private symbols should not appear in public header
-files, but rather in separate, private header files.
-
 \subsection{Lexical Variables}
 
-One declaration per line with a single place between 'my' and the identifier.
+One declaration per line with a single place between \code{my} and the identifier.
 
 \begin{verbatim}
@@ -560,5 +605,5 @@
 Do not put different types on the same line. Example:
 \begin{verbatim}
-my ($foo,  @fooArray);                  # WRONG!
+my ($foo, @fooArray);                  # WRONG!
 \end{verbatim}
 
@@ -614,5 +659,5 @@
 \item
 The first line after the opening brace should declare a list of lexical
-variables for input parameters and assign \code{@\_} to it.
+variables for input parameters and assign \code{@_} to it.
 
 \item
@@ -634,4 +679,5 @@
 }
 \end{verbatim}
+
 
 %------------------------------------------------------------------------------
@@ -679,5 +725,5 @@
 \begin{verbatim}
 return undef;                           # Correct
-return;                                 # Wrong!
+return;                                 # Avoid!
 
 return $myDisk->size;
@@ -687,6 +733,6 @@
 
 Note:  In absence of an explicit return statement Perl will return the results
-of the last statement executed.  A null return statement \code{return;} also
-causes the result of the last statement executed to be returned.
+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}
@@ -747,7 +793,13 @@
 the loop (for the update clause).
 
+\subsection{Perl style for, foreach Statements}
+
+\begin{verbatim}
+\end{verbatim}
+
 \subsection{while Statements}
 
 A \code{while} statement should have the following form:
+
 \begin{verbatim}
 while (condition) {
@@ -755,5 +807,7 @@
 }
 \end{verbatim}
+
 An empty \code{while} statement should have the following form:
+
 \begin{verbatim}
 while (condition) {}
@@ -763,4 +817,5 @@
 
 A \code{do-while} statement should have the following form:
+
 \begin{verbatim}
 do {
@@ -773,4 +828,13 @@
 Code labels should be indented to align with the previous level of
 indentation.
+
+\begin{verbatim}
+MYLABEL: while (condition) {
+    if (condition) {
+        next;
+    }
+}
+\end{verbatim}
+
 
 %------------------------------------------------------------------------------
@@ -816,6 +880,6 @@
 \item
 Binary operators should be separated from their operands by spaces.  Blank
-spaces should never separate unary operators such as a type cast, unary minus,
-increment (\code{++}), and decrement (\code{--}) from their operands. Examples:
+spaces should never separate unary operators such as a unary minus, increment
+(\code{++}), and decrement (\code{--}) from their operands. Examples:
 
 \begin{verbatim}
@@ -850,10 +914,9 @@
 \section{Naming Conventions}
 
-Naming conventions make programs more understandable by making them
-easier to read. They can also give information about the subroutine of
-the identifier -- for example, whether it's a constant, a subroutine, or
-a type -- which can be helpful in understanding the code.  Remember
-these are guidelines for improving readability; clarity should trump
-rigid adherence to the guideline.
+Naming conventions make programs more understandable by making them easier to
+read. They can also give information about the subroutine of the identifier --
+for example, whether it's a constant or a subroutine -- which can be helpful in
+understanding the code.  Remember these are guidelines for improving
+readability; clarity should trump rigid adherence to the guideline.
  
 { \small 
@@ -876,4 +939,6 @@
 \code{runFast();}\hfil\break
 \code{getBackground();}\hfil\break
+\code{_keepHandsOff();}\hfil\break
+\code{_notForPublicUse();}\hfil\break
 
 \\
@@ -881,14 +946,10 @@
 Variables &
 
-Except for variables, all instance, class, and class constants are in mixed
-case with Variable names should not start with underscore \code{_} as these
-names are, under some circumstances, reserved by Perl community convention.
-
-Variable names should be short yet meaningful. The choice 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 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.
+Variable names should be in mixed case and be short yet meaningful. The choice
+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
+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.
 
 &
@@ -905,13 +966,12 @@
 Constants &
 
-Perl's \code{constant} pragma should not be used as it merely generates
-subroutines with null prototypes.  'Constants' created this way can not be
-interpolated instead of strings.  Instead, use Lexical variables but with all
-capital letters.
+Perl's \code{constant} pragma should be used to declare constants.  Note:
+'constants' created this way can not be interpolated inside of double quoted
+strings.
 
 &
-\code{my $MAXLEN = 40;}\hfil\break
-\code{my @LENGTH = (2, 4, 8);}\hfil\break
-\code{my %CLASS = (raw => 1, processed => 2);}\hfil\break
+\code{use constant MAXLEN => 40;}\hfil\break
+\code{use constant LENGTH => qw(2, 4, 8);}\hfil\break
+\code{use constant CLASSES => (raw => 1, processed => 2);}\hfil\break
 
 \\
@@ -924,7 +984,7 @@
 &
 
-\code{Class::Data::Inheritable}\hfil\break
-\code{Time::HiRes}\hfil\break
-\code{XML::SimpleObject}\hfil\break
+\code{package Class::Data::Inheritable;}\hfil\break
+\code{package Time::HiRes;}\hfil\break
+\code{package XML::SimpleObject;}\hfil\break
 
 \\
@@ -932,4 +992,5 @@
 \end{tabular}
 }
+
 
 %------------------------------------------------------------------------------
@@ -1012,7 +1073,7 @@
 \end{verbatim}
 
-There are some famous problems with precedence in C.  In particular,
-expressions involving the combinations of \code{||} and \code{&&} should be
-fully parenthesized, as should all expressions containing bitwise operators:
+In particular, expressions involving the combinations of \code{||} and
+\code{&&} should be fully parenthesized, as should all expressions containing
+bitwise operators:
 
 \begin{verbatim}
@@ -1070,4 +1131,5 @@
 \end{verbatim}
 
+\end{document}
 %------------------------------------------------------------------------------
 \appendix				%Begin Appendices