Index: /trunk/doc/misc/perlCodeConventions.tex
===================================================================
--- /trunk/doc/misc/perlCodeConventions.tex	(revision 2331)
+++ /trunk/doc/misc/perlCodeConventions.tex	(revision 2332)
@@ -1,3 +1,3 @@
-%%% $Id: perlCodeConventions.tex,v 1.1 2004-11-09 03:55:35 jhoblitt Exp $
+%%% $Id: perlCodeConventions.tex,v 1.2 2004-11-11 01:55:58 jhoblitt Exp $
 \documentclass[panstarrs]{panstarrs}
 
@@ -155,7 +155,7 @@
 # Copyright (C) 2004  Joshua Hoblitt
 #
-# $Id: perlCodeConventions.tex,v 1.1 2004-11-09 03:55:35 jhoblitt Exp $
-
-use 5.008005;   #optional
+# $Id: perlCodeConventions.tex,v 1.2 2004-11-11 01:55:58 jhoblitt Exp $
+
+use 5.008005;   # optional
 
 use strict;     # not optional
@@ -212,9 +212,9 @@
 # Copyright (C) 2004  Joshua Hoblitt
 #
-# $Id: perlCodeConventions.tex,v 1.1 2004-11-09 03:55:35 jhoblitt Exp $
+# $Id: perlCodeConventions.tex,v 1.2 2004-11-11 01:55:58 jhoblitt Exp $
 
 package Foo;
 
-use 5.008005;   #optional
+use 5.008005;   # optional
 
 use strict;     # not optional
@@ -279,16 +279,16 @@
 squished up against the right margin, just indent 8 spaces
 instead.\footnote{This should be \emph{very} rare! Consider whether
-you should be e.g. factoring code into a function.}
+you should be e.g. factoring code into a subroutine.}
 
 \end{itemize}
 
-Here are some examples of breaking function calls:
-
-\begin{verbatim}
-someFunc(longExpression1, longExpression2, longExpression3, 
+Here are some examples of breaking subroutine calls:
+
+\begin{verbatim}
+someSub(longExpression1, longExpression2, longExpression3, 
          longExpression4, longExpression5);
  
-$var = someFunc1(longExpression1,
-                 someFunc2(longExpression2,
+$var = someSub(longExpression1,
+                 someSub(longExpression2,
  			  longExpression3)); 
 \end{verbatim}
@@ -322,26 +322,29 @@
 \section{Comments}
 
-Comments should not be used to `comment out code'; use \code{#if 0} instead:
-\begin{verbatim}
-#if 0
-    code that is not wanted just at present
-#endif
-\end{verbatim}
-This has two advantages:
-\begin{itemize}
-\item  The code can easily be reinstated.
-\item  Related blocks of code can be removed with
-\begin{verbatim}
-#define IGNORE_RHL 1
-#if !IGNORE_RHL
-    ...
-#endif
-...
-#if !IGNORE_RHL
-    ...
-#endif
-\end{verbatim}
-This type of \code{#define} may appear within the main body of the file.
-\end{itemize}
+\subsection{Deactivating Code}
+
+Comments should not be used to comment out large sections of code.  When
+deactivating 2 or fewer lines of code a \code{#} should be used at the very
+beginning of the line(s).
+
+Example of deactivating a single line code.
+\begin{verbatim}
+    if ($foo) {
+#        print( "foo" );
+    }
+\end{verbatim}
+
+When deactivating 3 or more lines of code an \code{if} statement should be used
+with a false boolean value.  The opening and closing of the \code{if} statement
+must be at the very beginning of the line.
+
+Example of deactivating multiple lines of code.
+\begin{verbatim}
+if (0) {
+    if ($foo) {
+        print( "foo" );
+    }
+}
+\end{verbatim}
 
 Comments should be used to give overviews of code and provide
@@ -370,58 +373,37 @@
 \subsection{Implementation Comment Formats}
 
-Programs can have four styles of implementation comments: block,
-single-line, trailing, and end-of-line.
-
-\subsubsection{Block Comments }
-\label{ImplBlockComments} 
-
-Block comments are used to provide descriptions of files, functions,
-data structures and algorithms. Block comments may be used at the
-beginning of each file and before each function. They can also be used
-in other places, such as within functions. Block comments inside a
-function should be indented to the same level as the code they
-describe.
-
-See also Documentation Comments (\S\ref{DocComments}).
+Programs can have three styles of implementation comments: single-line,
+multi-line and trailing.
 
 \subsubsection{Single-Line Comments}
-\label{SingleLineComment} 
-
-Short comments can appear on a single line indented to the level of
-the code that follows. If a comment can't be written in a single line,
-it should follow the block comment format (\S\ref{ImplBlockComments}).
+
+Short comments can appear on a single line indented to the level of the code
+that follows.  The comment should appear above the code that it is describe and
+must have a space between the \code{#} and the first text.
+
+Example of a single-line comment.
+\begin{verbatim}
+# some words
+\end{verbatim}
+
+\subsubsection{Multi-Line Comments}
+
+Merely a repitition of single-line comments.
 
 \subsubsection{Trailing Comments}
-\label{col40} 
+\label{col41} 
 
 Very short comments can appear on the same line as the code they
-describe, and should be indented to column 40\footnote{In emacs, this
+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 C code: 
-\begin{verbatim}
-if (a == 2) {
-    return TRUE;                          /* special case */
+Here's an example of a trailing comment in Perl code: 
+\begin{verbatim}
+if ($a == 2) {
+    return TRUE;                        # special case
 } else {
-    return isPrime(a);                    /* works only for odd a */
-}
-\end{verbatim}
-
-\subsubsection{End-Of-Line Comments}
-
-The \code{//} comment delimiter can comment out a complete line
-or only a partial line; as for trailing comments, the comment should
-start in column 40.  It shouldn't be used on consecutive multiple
-lines for text comments.  Examples of both styles follow:
-
-\begin{verbatim}
-if (foo > 1) {
-
-    // Do a double-flip.
-    ...
-} else {
-    return false;          // Explain why here.
+    return isPrime($a);                 # works only for odd a
 }
 \end{verbatim}
@@ -430,44 +412,31 @@
 \label{DocComments} 
 
-Doxygen\footnote{{\tt  www.doxygen.org}}  will   be  used  to  produce
-documentation of the types,  functions and variables without requiring
-much  extra  effort  for   the  programmer.   Comments  starting  with
-particular characters  (``tags'') are used by Doxygen  to identify the
-relevant code to be documented.
-
-Functions shall be tagged for Doxygenation by pre-pending them with a
-block comment (\S\ref{ImplBlockComments}) which starts with a
-\code{/**} instead of the usual \code{/*}.
-
-Variables shall be tagged for Doxygenation by appending their
-declaration with an end-of-line comment which starts with a
-\code{///<} instead of the usual \code{//}.
-
-An example of a function definition employing Doxygen-compatible
-comments follows:
-
-\begin{verbatim}
-/** This is a really cool function.
- *  It does many really cool things.
- */
-int reallyCoolFunction(int aNumber,     ///< This is a number 
-                       float aRealNumber ///< This is a real number
-                       )
+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
 {
-    char *aString;                      ///< This is a string used to do stuff.
-
-    /* Do really cool stuff */
-    ...
-}
-\end{verbatim}
-
-If you need to give information about a type, interface, or variable
-that isn't appropriate for doxygenation, use a normal implementation
-block comment (\S\ref{ImplBlockComments}) or single-line comment
-(\S\ref{SingleLineComment}) immediately \textit{before} the code (as
-exampled above). For example, details about the implementation of a
-type should go in in such an implementation block comment
-\textit{before} the start of the implementation, not in the doxygen
-comment.
+    my ($aNumber, $aString) = @_;
+
+    # Do really cool stuff
+
+    return $aThing;
+}
+\end{verbatim}
+
+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).
 
 %------------------------------------------------------------------------------
@@ -479,29 +448,26 @@
 files, but rather in separate, private header files.
 
-\subsection{Number Per Line}
-
-One declaration per line is recommended since it encourages
-commenting. In other words,
-\begin{verbatim}
-int level;                              // indentation level
-int size;                               // size of table
-\end{verbatim}
+\subsection{Lexical Variables}
+
+One declaration per line with a single place between 'my' and the identifier.
+
+\begin{verbatim}
+my $level;                              # indentation level
+my $size;                               # size of table
+\end{verbatim}
+
 is preferred over
-\begin{verbatim}
-int level, size;
-\end{verbatim}
+
+\begin{verbatim}
+my ($level, $size);
+\end{verbatim}
+
+In almost all situations with the exception of when parameters are being passed
+into a subrutine.
+
 Do not put different types on the same line. Example:
 \begin{verbatim}
-int foo,  fooarray[];                   // WRONG!
-\end{verbatim}
-
-Note: The examples above use one space between the type and the identifier. Another acceptable alternative is to use tabs, e.g.:
-\begin{verbatim}
-int    level;                           // indentation level
-int    size;                            // size of table
-Object    currentEntry;                 // currently selected table entry
-\end{verbatim}
-
-(Note that the comments are indented to column 40, as per section~\ref{col40}).
+my ($foo,  @fooArray);                  # WRONG!
+\end{verbatim}
 
 \subsection{Initialization}
@@ -521,93 +487,67 @@
 associates their declaration with their use.
 
-For example, declarations are naturally mixed with assertions:
-\begin{verbatim}
-void function(REGION *reg)                      // image of the sky
+
+Indexes of loops should usually be declared on the line above loop statement.
+
+\begin{verbatim}
+my $i = 0;
+for (i < $maxLoops) {
+    # do stuff
+
+    $i++;
+}
+\end{verbatim}
+
+Avoid \code{local} declarations that hide user declared variables from higher
+level scopes. For example, do not declare the same variable name in an inner
+block:
+
+\begin{verbatim}
+my $count;
+...
+sub mySubroutine
 {
-    assert (reg != NULL);
-    const int nrow = reg->nrow;
-    assert (reg->type == psType_U16);
-    const psTypeU16 *rows = reg->rows;
+    local $count;
     ...
 }
 \end{verbatim}
 
-Indexes of \code{for} loops should usually
-be declared in the \code{for} statement (the declarations appear
-in the scope of the braces):
-\begin{verbatim}
-for (int i = 0; i < maxLoops; i++) {
+\subsection{Subroutine Declarations}
+
+When coding Perl subroutines the following formatting rules should be
+followed:
+
+\begin{itemize}
+\item 
+Subroutine declarations should be preceeded by a short comment describing what
+the subroutine does.  These documentation comments should include a brief
+desription as well as other warnings, bugs, etc. as needed.
+
+\item
+The subroutine body's open brace \CODE.{. should be in column 1 of the next
+line.
+
+\item
+The first line after the opening brace should declare a list of lexical
+variables for input parameters and assign \code{@\_} to it.
+
+\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.{..
+
+\item
+The last line before the closing brace must explicity declare a return value.
+\end{itemize}
+
+\begin{verbatim}
+sub subName
+{
+    my ($param1, $param2, ...) = @_;
     ...
-}
-\end{verbatim}
-
-Avoid local declarations that hide declarations at higher levels. For
-example, do not declare the same variable name in an inner block:
-\begin{verbatim}
-static int count;
-...
-void myFunction(void)
-{
-    if (condition) {
-    int count = 0;                      // AVOID!
-    ...
-    }
-    ...
-}
-\end{verbatim}
-
-\subsection{Function Declarations}
-
-When coding C functions the following formatting rules should be
-followed:
-
-\begin{itemize}
-\item 
-Function declarations should be preceeded by a short comment
-describing what the function does.  These comment blocks should
-include doxygen-style comments to provide a brief desription as well
-as other warnings, bugs, etc as needed.
-
-\item The function's type should appear on the same line as the
-function declaration.
-
-\item All arguments should be declared with their types; i.e. no
-classic-C declarations like:
-\begin{verbatim}
-int main(ac, av)
-         int ac;
-         char **av;
-\end{verbatim}
-
-\item No space between a function name and the parenthesis \code{(} starting
-its parameter list \matchBracket{)}
-
-\item The function body's open brace \CODE.{. should be in column 1 of the next line:
-\begin{verbatim}
-void function(void)
-{
-    ...
-}
-\end{verbatim}
-
-\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.{..
-
-\begin{verbatim}
-void find_neos(const REGION *sky, const char *descrip)
-{
-    struct {
-        int x, y;
-    } work[10];
-    int ivar;
-
-    while(isspace(*descrip++)) {}         // skip white space
-    descrip--;                            // one too far. Not great code...
-
-    ...
-}
-\end{verbatim}
-\end{itemize}
+
+    return $val;
+}
+\end{verbatim}
 
 %------------------------------------------------------------------------------
@@ -799,7 +739,7 @@
 \begin{itemize}
 
-\item Between the local variables in a function and its first statement
-
-\item Between logical sections inside a function to improve readability
+\item Between the local variables in a subroutine and its first statement
+
+\item Between logical sections inside a subroutine to improve readability
 \end{itemize}
 
@@ -816,7 +756,7 @@
 \end{verbatim}
 
-Note that a blank space should not be used between a function name and
+Note that a blank space should not be used between a subroutine name and
 its opening parenthesis. This helps to distinguish keywords from
-function calls.
+subroutine calls.
 
 \item A blank space should appear after commas in argument lists.
@@ -854,6 +794,6 @@
 
 Naming conventions make programs more understandable by making them
-easier to read. They can also give information about the function of
-the identifier -- for example, whether it's a constant, a function, or
+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
@@ -885,12 +825,12 @@
 \\
 
-Functions &
-
-The names of all externally visible functions (i.e. all those that are
+Subroutines &
+
+The names of all externally visible subroutines (i.e. all those that are
 not declared \code{static}) should be verbal phrases, in mixed case.
 
 Namespaces should be protected by using special naming prefixes to
 restrict the name space in particular libraries.  For example, the
-PSLib functions are all prefixed with \code{ps}.
+PSLib subroutines are all prefixed with \code{ps}.
 
 &
@@ -954,10 +894,10 @@
 \subsection{When to Make Symbols Global}
 
-Declare all functions and top-level variables \code{static} within a
+Declare all subroutines and top-level variables \code{static} within a
 file if they are not needed outside of the file.  {\bf Note:} do not
 confuse this use of \code{static} with its usage to make
-auto-variables within a function persistent.
-
-A name (whether of a variable, a function, or a type) shall start
+auto-variables within a subroutine persistent.
+
+A name (whether of a variable, a subroutine, or a type) shall start
 \code{ps} (or \code{p_ps}) if and only if it is visible at global
 scope.  The distinction is that \code{p_ps} names are not part of the
@@ -1103,10 +1043,10 @@
 \end{verbatim}
 
-\subsubsection{Functions that Take No Parameters}
-
-When a function takes no arguments, it should be explicitly declared
+\subsubsection{Subroutines that Take No Parameters}
+
+When a subroutine takes no arguments, it should be explicitly declared
 as \code{void}:
 \begin{verbatim}
-static type myFunction(void)
+static type mySubroutine(void)
 {
     ...
@@ -1150,5 +1090,5 @@
 
 \item 
-Use \code{\notused} to indicate unused arguments to a function:
+Use \code{\notused} to indicate unused arguments to a subroutine:
 e.g.
 \begin{verbatim}
@@ -1327,5 +1267,5 @@
 \item
   Added naming conventions for constructors, destructors, and conversion
-  functions.
+  subroutines.
 
 \item
@@ -1337,5 +1277,5 @@
 
 \item
-  Specified that functions taking no arguments should be explicitly
+  Specified that subroutines taking no arguments should be explicitly
   specified as \code{(void)} (avoiding complaints on some compilers,
   e.g. on SGIs).
@@ -1418,5 +1358,5 @@
 (add-hook 'panstarrs-c-mode-hook
 	  '(lambda ()
-	     (set (make-variable-buffer-local 'comment-indent-function)
+	     (set (make-variable-buffer-local 'comment-indent-subroutine)
 		  'panstarrs-comment-indent)))
 \end{verbatim}