Changeset 2349 for trunk/doc/misc/perlCodeConventions.tex

Timestamp:

Nov 12, 2004, 11:14:27 AM (22 years ago)

Author:

jhoblitt

Message:

add limitations blurb
converted Programming Practices

File:

• trunk/doc/misc/perlCodeConventions.tex (modified) (12 diffs)

trunk/doc/misc/perlCodeConventions.tex

@@ -1 @@
-%%% $Id: perlCodeConventions.tex,v 1.5 2004-11-11 04:02:34 jhoblitt Exp $
+%%% $Id: perlCodeConventions.tex,v 1.6 2004-11-12 21:14:27 jhoblitt Exp $
 \documentclass[panstarrs]{panstarrs}
 
@@ -64 +64 @@
 Such an adaption is explicitly permitted by the Sun Microsystems
 copyright notice (Copyright.doc.html).
+
+\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
+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
+example of this).  This document does not attempt to define the coding style
+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.
 
 \subsection{To whom should I Complain?}
@@ -155 +166 @@
 # Copyright (C) 2004  Joshua Hoblitt
 #
-# $Id: perlCodeConventions.tex,v 1.5 2004-11-11 04:02:34 jhoblitt Exp $
+# $Id: perlCodeConventions.tex,v 1.6 2004-11-12 21:14:27 jhoblitt Exp $
 
 use 5.008005;   # optional
@@ -212 +223 @@
 # Copyright (C) 2004  Joshua Hoblitt
 #
-# $Id: perlCodeConventions.tex,v 1.5 2004-11-11 04:02:34 jhoblitt Exp $
+# $Id: perlCodeConventions.tex,v 1.6 2004-11-12 21:14:27 jhoblitt Exp $
 
 package Foo;
@@ -811 +822 @@
 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 varibles but with all
+interpolated instead of strings.  Instead, use Lexical variables but with all
 capital letters.
 
@@ -841 +852 @@
 \section{Programming Practices}
 
-%\subsection{When to Make Symbols Global}
-
-%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 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
-%documented APIs, but need to be exposed for some reason.
+\subsection{When to Make Symbols Global}
+
+Only declare variables as package variables (\code{our}) if they are going to
+be exported into another namespace.  All other variables within a namespace
+should be declared as lexical.
+
+\begin{verbatim}
+package someModule;
+
+use base qw( Exporter );
+
+our @EXPORT_OK = qw( $foo $bar );
+
+\end{verbatim}
 
 \subsection{Constants}
@@ -889 +903 @@
 performance. This is the job of the compiler. Example:
 \begin{verbatim}
-d = (a = b + c) + r;                    // AVOID!
+$d = ($a = $b + $c) + $r;               # AVOID!
 \end{verbatim}
 
 should be written as
 \begin{verbatim}
-a = b + c;
-d = a + r;
+$a = $b + $c;
+$d = $a + $r;
 \end{verbatim}
 
@@ -909 +923 @@
 
 \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}
 
 There are some famous problems with precedence in C.  In particular,
-expressions involving the combinations of \code{||} and
-\code{&&} should be fully parenthesised, as should all
-expressions containing bitwise operators:
-\begin{verbatim}
-if ((a == b && c == d) || e == f)
-l << (j + k)
-(l << j) + k
-(i & b) | c
+expressions involving the combinations of \code{||} and \code{&&} should be
+fully parenthesized, as should all expressions containing bitwise operators:
+
+\begin{verbatim}
+if (($a == $b && $c == $d) || $e == $f)
+$l << ($j + $k)
+($l << $j) + $k
+($i & $b) | $c
 \end{verbatim}
 
@@ -927 +941 @@
 
 Try to make the structure of your program match the intent. Example:
+
 \begin{verbatim}
 if (booleanExpression) {
@@ -934 +949 @@
 }
 \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:
+
+If you're concerned that the reader may not know that \code{booleanExpression}
+is boolean, use:
+
 \begin{verbatim}
 return (booleanExpression ? true : false);
@@ -945 +964 @@
 
 Similarly,
+
 \begin{verbatim}
 if (condition) {
-    return x;
-}
-return y;
+    return $x;
+}
+return $y;
 \end{verbatim}
 should be written as
@@ -958 +978 @@
 \subsubsection{Expressions before `?' in the Conditional Operator }
 
-If an expression containing a binary operator appears before the \code{?} in the ternary \code{?: }operator, it should be parenthesized. Example:
-\begin{verbatim}
-(x >= 0) ? x : -x;
-\end{verbatim}
-
-\subsubsection{Subroutines that Take No Parameters}
-
-When a subroutine takes no arguments, it should be explicitly declared
-as \code{void}:
-\begin{verbatim}
-static type mySubroutine(void)
-{
-    ...
-}
-\end{verbatim}
-
-
-\subsubsection{Special Comments}
-
-Doxygen has special comments which are used to provide specific notes
-in the code.  These are added in as special entries and sections in
-the Doxygen-generated documentation.  These special comments should be
-used in addition to the Doxygen usage to make these types of
-conditions easily searchable.
-
-\begin{itemize}
-\item 
-Use \code{\warning} in a comment to flag something that is bogus but works.
-
-\item 
-Use \code{\bug} to flag something that is bogus and broken.
-
-\item 
-Use \code{\todo} to note additional work to be done 
-
-\item 
-Use \code{\note} to make other general notes 
-
-\item 
-Use \code{\test} to list test cases 
-
-\item
-Use \code{\notreached} to indicate a line of code that cannot be reached,
-e.g.
-\begin{verbatim}
-if (sqrt(x) < 0) {
-    psAbort();                            // never returns
-    exit(1);                              // NOTREACHED
-}
-\end{verbatim}
-
-\item 
-Use \code{\notused} to indicate unused arguments to a subroutine:
-e.g.
-\begin{verbatim}
-type psWorkHard(const Region *restrict reg, // Region to operate on
-                int myConst,            // magic value
-                int magicNumber         // NOTUSED; reserve for next version
-                )
-{
-   ...
-}
-\end{verbatim}
-\end{itemize}
+If an expression containing a binary operator appears before the \code{?} in
+the ternary \code{?: }operator, it should be parenthesized. Example:
+
+\begin{verbatim}
+($x >= 0) ? $x : -$x;
+\end{verbatim}
 
 %------------------------------------------------------------------------------