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

Timestamp:

Nov 10, 2004, 6:02:34 PM (22 years ago)

Author:

jhoblitt

Message:

converted white space and naming conventions

File:

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

trunk/doc/misc/perlCodeConventions.tex

@@ -1 @@
-%%% $Id: perlCodeConventions.tex,v 1.4 2004-11-11 02:27:56 jhoblitt Exp $
+%%% $Id: perlCodeConventions.tex,v 1.5 2004-11-11 04:02:34 jhoblitt Exp $
 \documentclass[panstarrs]{panstarrs}
 
@@ -155 +155 @@
 # Copyright (C) 2004  Joshua Hoblitt
 #
-# $Id: perlCodeConventions.tex,v 1.4 2004-11-11 02:27:56 jhoblitt Exp $
+# $Id: perlCodeConventions.tex,v 1.5 2004-11-11 04:02:34 jhoblitt Exp $
 
 use 5.008005;   # optional
@@ -212 +212 @@
 # Copyright (C) 2004  Joshua Hoblitt
 #
-# $Id: perlCodeConventions.tex,v 1.4 2004-11-11 02:27:56 jhoblitt Exp $
+# $Id: perlCodeConventions.tex,v 1.5 2004-11-11 04:02:34 jhoblitt Exp $
 
 package Foo;
@@ -698 +698 @@
 
 \begin{itemize}
-
 \item Between the local variables in a subroutine and its first statement
 
@@ -708 +707 @@
 Blank spaces should be used in the following circumstances:
 \begin{itemize}
-
-\item A keyword followed by a parenthesis should be separated by a space. Example:
+\item
+A keyword followed by a parenthesis should be separated by a space. Example:
+
 \begin{verbatim}
 while (true) {
@@ -716 +716 @@
 \end{verbatim}
 
-Note that a blank space should not be used between a subroutine name and
-its opening parenthesis. This helps to distinguish keywords from
-subroutine calls.
-
-\item A blank space should appear after commas in argument lists.
-
-\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:
-\begin{verbatim}
-    a += c + d;
-    a = (a + b) / (c * d);
+Note that a blank space should not be used between a subroutine name and its
+opening parenthesis. This helps to distinguish keywords from subroutine calls.
+
+\item
+A blank space should appear after commas in argument lists.
+
+\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:
+
+\begin{verbatim}
+    $a += $c + $d;
+    $a = ($a + $b) / ($c * $d);
     
-    while (*d++ = *s++) {                 // Tricky way of copying until '\0'
-        n++;
+    while ($d++ = $s++) {
+        $n++;
     }
-    printf ("size is %d\n", foo);
-\end{verbatim}
-
-\item The expressions in a \code{for} statement should be
-separated by blank spaces. Example:
+    printf("size is %d\n", $foo);
+\end{verbatim}
+
+\item
+The expressions in a \code{for} statement should be separated by blank spaces.
+Example:
 
 \begin{verbatim}
@@ -766 +767 @@
 \textbf{Examples} \\
 
-Typedefs &
-
-Type names should be nouns, in mixed case with the first letter of
-each internal word capitalized.  Little words, such as 'for', 'to',
-'at', etc, may be written in all lower-case or separated with
-underscores if it makes the name clearer.
-
-If and only if the type is visible at global scope, the
-type name should start with \code{ps}.
-
-Try to keep your type names simple and descriptive. Use whole
-words-avoid acronyms and abbreviations (unless the abbreviation is
-much more widely used than the long form, such as URL or HTML).
-
- &
-typedef struct {...} psRaster;\hfil\break
-typedef struct {...} psImage;
+Subroutines &
+
+The names of all public subroutines (and methods) should be verbal phrases, in
+mixed case.
+
+Private subroutines (and methods) should follow the same rules as public
+subroutines but be prefixed with an underscore.
+
+&
+
+\code{run();}\hfil\break
+\code{runFast();}\hfil\break
+\code{getBackground();}\hfil\break
+
 \\
 
-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 subroutines are all prefixed with \code{ps}.
+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.
 
 &
 
-\code{psRun(int ID);}\hfil\break
-\code{psRunFast(float velocity);}\hfil\break
-\code{psGetBackground(void);}\hfil\break
+\code{$i;}\hfil\break
+\code{$c;}\hfil\break
+\code{$myWidth;}\hfil\break
 \hfil\break
-\code{p_psForgeSignature(const char *name);}
-
-\\
-
-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 the C
-standard. Non-globally visible words should start with a lowercase
-first letter; Internal words start with capital letters.
-
-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.
-
-&
-\code{int i;}\hfil\break
-\code{char c;}\hfil\break
-\code{float myWidth;}\hfil\break
-\hfil\break
-\code{int pseudo;}\hfil\break
-\code{int p_psMyFiddleFactor;}\hfil\break
+\code{$pseudo;}\hfil\break
+\code{$myFiddleFactor;}\hfil\break
 
 \\
  
-Constants
+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 varibles but with all
+capital letters.
 
 &
-
-Constants used to e.g. dimension arrays should be set using the
-\code{#define}; \code{const} variables should not be used, especially
-in header files.  Symbolic values should usually be declared using
-enumerated types.
+\code{my $MAXLEN = 40;}\hfil\break
+\code{my @LENGTH = (2, 4, 8);}\hfil\break
+\code{my %CLASS = (raw => 1, processed => 2);}\hfil\break
+
+\\
+
+Namespaces &
+
+Must start with a capitalized letter but otherwise follow the same naming
+conventions as variables.
 
 &
-\code{#define PS_MAXLEN 40}\hfil\break
-\CODE|enum { PS_ONE = 1, PS_TWO = 2 };|\hfil\break
+
+\code{Class::Data::Inheritable}\hfil\break
+\code{Time::HiRes}\hfil\break
+\code{XML::SimpleObject}\hfil\break
+
+\\
 
 \end{tabular}
@@ -852 +841 @@
 \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}
+
+%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{Constants}
@@ -870 +859 @@
 in a \code{for} loop as counter values.  
 
-\subsection{Type Qualifiers (const and restrict)}
-
-All interfaces and type definitions should use \code{const} and
-\code{restrict} wherever appropriate. For example,
-\begin{verbatim}
-typedef struct {
-    int n;
-    float *restrict vec;
-} psVec;
-
-psVec *psVecAdd(const restrict* psVec s1, const restrict* psVec s2); 
-\end{verbatim}
-
-\textit{{\bf Note:} compilers are free to ignore the \code{restrict}
-keyword, so all code should be written to explicitly handle aliasing}.
-
-\subsection{structs and typedefs}
-
-All structs should be defined as \code{typedef}s.
-
-A struct should not include a struct
-tag unless it's self-referential; E.g.
-\begin{verbatim}
-typedef struct myStruct {               // Omit "myStruct"
-    int x;
-} myStruct;
-
-typedef struct yourStruct {             // OK
-    struct yourStruct *next;
-    int x;
-} yourStruct;
-\end{verbatim}
-
 \subsection{Variable Assignments}
 
@@ -909 +865 @@
 
 \begin{verbatim}
-row0 = col0 = 0;
-sum = sumx = sumy = 0;
-\end{verbatim}
-
-Do not use the assignment operator in a place where it can be easily confused with the equality operator. Example:
-\begin{verbatim}
-if (c++ = d++) {                        // AVOID!
+$row0 = $col0 = 0;
+$sum = $sumx = $sumy = 0;
+\end{verbatim}
+
+Do not use the assignment operator in a place where it can be easily confused
+with the equality operator. Example:
+
+\begin{verbatim}
+if ($c++ = $d++) {                      # AVOID!
     ...
 }
 \end{verbatim}
+
 should be written as
-\begin{verbatim}
-if ((c++ = d++) != 0) {
+
+\begin{verbatim}
+if (($c++ = $d++) != 0) {
     ...
 }