Index: /trunk/doc/misc/perlCodeConventions.tex
===================================================================
--- /trunk/doc/misc/perlCodeConventions.tex	(revision 2402)
+++ /trunk/doc/misc/perlCodeConventions.tex	(revision 2403)
@@ -1,3 +1,3 @@
-%%% $Id: perlCodeConventions.tex,v 1.26 2004-11-23 02:53:47 jhoblitt Exp $
+%%% $Id: perlCodeConventions.tex,v 1.27 2004-11-23 04:24:52 jhoblitt Exp $
 \documentclass[panstarrs]{panstarrs}
 
@@ -77,10 +77,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.  This document also only contains brief discussion of Perl's
+project.  This document only contains brief discussion of Perl's
 Object-Oriented features and none of it's more advanced features.
 
 \subsection{Applicability}
 
-This document is intended to be relevant with Perl 5.8.0 or later.
+This document is intended to be relevant to Perl 5.8.0 or later.
 
 \subsection{To whom should I Complain?}
@@ -148,5 +148,5 @@
 \begin{itemize}
 \item 
-A Bourne shell "she-bang" for perl.  \code{#!/usr/bin/perl}.
+A Bourne shell ``she-bang'' for perl.  \code{#!/usr/bin/perl}.
 
 \item 
@@ -155,6 +155,6 @@
 
 \item
-A minimum perl version requirement in long form (vStrings are not allowed).
-Where \code(requirement = revision + version / 1000 + subversion /
+An optional 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}
@@ -164,5 +164,5 @@
 
 \item 
-Any base classes.
+Any modules to include. 
 
 \item 
@@ -202,5 +202,5 @@
 
 \item
-A minimum perl version requirement in long form (vStrings are not allowed).
+An optional 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
@@ -210,4 +210,10 @@
 A \code{use strict} and \code{use warnings} declaration.
 
+\item
+A module \code{VERSION} declaration.
+
+\item 
+Any ``base'' classes. 
+
 \item 
 Any modules to include. 
@@ -237,8 +243,9 @@
 
 \subsubsection{Plain Old Documentation}
+\label{pod} 
 
 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}).
+\code{__END__} token and the \code{.pod} file that should accompany a module
+(\code{.pm}).
 
 e.g. for file Foo.pod:
@@ -432,34 +439,14 @@
 \end{verbatim}
 
-\subsection{Documentation Comments}
+\subsection{API Comments}
 \label{DocComments} 
 
 Plain Old Documentation format or Pod will be used to produce documentation of
-the subroutines and variables in the exposed API.  Pod sections will appear
-above the section of code that they describe.
-
-An example of a Pod section defining the API of a subroutine.
-
-\begin{verbatim}
-    =item * reallyCoolSubroutine
-
-    Accepts a real number and a string.  Does some really cool stuff with it and
-    returns a really cool thing.
-
-    =cut
-
-    sub reallyCoolSubroutine
-    {
-        my ($aNumber, $aString) = @_;
-
-        # Do really cool stuff
-
-        return $aThing;
-    }
-\end{verbatim}
+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
 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 \textit{before} the code (as exampled above).
 
 
@@ -511,9 +498,10 @@
 \subsection{Initialization}
 
-Try to initialize local variables where they're declared.  Do not initialize
-variables with an empty string or list - this is pointless.
-
-reason not to initialize a variable where it's declared is if the
-initial value depends on some computation occurring first.
+Try to initialize local variables where they're declared.
+
+Do not initialize variables with an empty string or list - this is pointless.
+
+A reason not to initialize a variable where it's declared is if the initial
+value depends on some computation occurring first.
 
 In some cases it may be necessary to initialize a variable to suppress
@@ -534,7 +522,7 @@
 \begin{itemize}
 \item 
-Subroutine declarations should be preceded by a short comment describing what
-the subroutine does.  These documentation comments should include a brief
-description as well as other warnings, bugs, etc. as needed.
+Subroutine declarations may be preceded by a short comment describing what the
+subroutine does.  These comments should include a brief description as well as
+other warnings, bugs, etc. as needed.
 
 \item
@@ -547,6 +535,6 @@
 
 \item
-Closing brace \CODE.}. starts a line by itself, except when it is a null
-statement the \CODE.}. should appear immediately after the \CODE.{..
+Closing brace \CODE.}. starts a line by itself.  Null statement should have the
+closing brace immediately after the opening brace.  e.g. \CODE.{}.
 
 \item
@@ -684,6 +672,6 @@
 \subsection{Perl style for, foreach Statements}
 
-A Perlish \code{for} or \code{foreach} statement (also known as an iterator)
-should have the following form:
+A Perlish \code{for} or \code{foreach} statement should have the following
+form:
 
 \begin{verbatim}
@@ -1042,5 +1030,5 @@
 
 If an expression containing a binary operator appears before the \code{?} in
-the ternary \code{?: }operator, it should be parenthesized. Example:
+the ternary \code{?:} operator, it should be parenthesized. Example:
 
 \begin{verbatim}
@@ -1062,5 +1050,5 @@
 
 Don't use ``bare-words'' as filehandles except for \code{STDIN}, \code{STDOUT},
-or \code{STDERR}.
+and \code{STDERR}.
 
 \begin{verbatim}
@@ -1080,4 +1068,18 @@
 \end{verbatim}
 
+\subsubsection{Chop vs. Chomp}
+
+Don't use \code{chop} to remove newline characters as it will remove any
+character (newline or not).
+
+\begin{verbatim}
+    my $foo = "baz\n";                  # string with newline
+    
+    chomp($foo);                        # removes "\n" - Correct
+    chomp($foo);                        # chomping the same string twice is safe
+
+    chop($foo);                         # removes "z" - AVOID!
+\end{verbatim}
+
 %------------------------------------------------------------------------------
 \appendix				%Begin Appendices