Changeset 514

Timestamp:

Apr 23, 2004, 11:57:43 AM (22 years ago)

Author:

eugene

Message:

changes to coding requirements from MHPCC comments

Location:

trunk/doc

Files:

• design/specs.tex (modified) (6 diffs)
• misc/codeConventions.tex (modified) (16 diffs)
• pslib/psLibSRS.tex (modified) (7 diffs)

trunk/doc/design/specs.tex

@@ -1 @@
-%%% $Id: specs.tex,v 1.5 2004-04-15 01:38:47 eugene Exp $
+%%% $Id: specs.tex,v 1.6 2004-04-23 21:57:43 eugene Exp $
 \documentclass[panstarrs]{panstarrs}
 
@@ -172 +172 @@
 \subsubsection{Software Coding Requirements}
 
-\paragraph{CSCI Deliverable}
-
-All final source code generated for the IPP is to be delivered via
-CVS, including the test code.  CVS revision history shall be included
-and made available via CVS.
-
 \paragraph{Languages}
 
@@ -205 +199 @@
 defined in the document TBD}.
 
+\paragraph{Naming Conventions}
+
+Header files must have names starting \code{ps} or \code{p_ps} for
+private interface definitions. The latter must appear in a
+subdirectory \code{private} of whichever directory is being searched
+for the public header files.
+
+Functions visible at global scope which are part of the public API
+must have names begining with \code{ps}, and follow the naming
+conventions in the coding standard.  Functions that are visible at
+global scope but which are not part of the public interface must have
+names begining with \code{p_ps}.  Functions that are local to a file
+must \textit{not} start \code{ps} (or \code{p_ps}).
+ 
+Variables visible at global scope which are part of the public API
+must have names begining with \code{ps}, and follow the naming
+conventions in the coding standard.  Variables that are visible at
+global scope but which are not part of the public interface must have
+names begining with \code{p_ps}.  Variables that are local to a file
+must \textit{not} start \code{ps} (or \code{p_ps}).
+
+The names of all enumerated types and C-preprocessor symbols (but not
+variables declared \code{const}) must start with \code{PS_}, in the
+case of public symbols, or \code{P_PS_}, for private symbols.  The
+rest of the name must be uppercase with words separated by underscores
+(\code{_}). An exception is the case of system utilities implemented
+as macros, in which case the names must conform to the convention for
+function names.
+
+When defining a function to convert from one type to another, the name
+should be of the form \code{psOldToAlloc}, e.g.\hfil\break
+\code{psEquatorialToEcliptic} (\emph{not}
+\code{psEquatorial2Ecliptic}).
+
+\paragraph{C Programming Guidelines}
+
+Functions that assign to a variable should list that argument
+\textit{first}, following the pattern of \code{strcpy}; e.g.
+\begin{verbatim}
+void psAddToVector(restrict psVec *outVec, const restrict psVec *inVec,
+                   int val);
+\end{verbatim}
+
+Type definitions should always be accompanied by prototypes for their
+constructors and destructors, following these guidelines:
+
+\begin{itemize}
+\item The constructor name should consist of the type name followed by
+\code{Alloc}; e.g. a type \code{psImage} would be created by a
+function
+\begin{verbatim}
+psImage *psImageAlloc(int nrow, int ncol);
+\end{verbatim}
+
+\item The type should be freed with a destructor named \code{typeFree}, e.g.
+\begin{verbatim}
+void psImageFree(psImage *img);
+\end{verbatim}
+
+\item The constructor must never return \code{NULL}, and no code calling the
+constructor should ever check the return value.
+
+\item The destructor must not return a value.
+
+\item The destructor must handle being passed \code{NULL} by simply
+returning immediately. This should not be treated as an error
+condition.
+
+\item Constructors and Destructors should use the memory reference
+  counter facilities of the PSLib memory management system.
+
+\end{itemize}
+
 \paragraph{Commenting and Documentation}
 
@@ -223 +290 @@
 Source code version control shall be implemented with CVS.  
 
+\paragraph{CSCI Deliverable}
+
+All final source code generated for the IPP is to be delivered via
+CVS, including the test code.  CVS revision history shall be included
+and made available via CVS.
+
 \paragraph{Platform architectures and operating systems}
 
@@ -238 +311 @@
 such as those caused by lex-generated code.  
 
-Although the code must compile successfully under all three listed
+Although the code must compile successfully under both listed
 operating systems, unit testing should only be performed for the
 x86/Linux combination.
@@ -244 +317 @@
 \paragraph{Software Configuration}
 
-\tbd{Makefiles, directory structures, UPS, etc}
+\tbd{deferred}
 
 \subsubsection{Architectural Components}

trunk/doc/misc/codeConventions.tex

@@ -1 @@
-%%% $Id: codeConventions.tex,v 1.14 2004-04-22 22:33:38 price Exp $
+%%% $Id: codeConventions.tex,v 1.15 2004-04-23 21:57:43 eugene Exp $
 \documentclass[panstarrs]{panstarrs}
 
@@ -171 +171 @@
 e.g. for file \file{psThing.h}:
 \begin{verbatim}
-/*
+/** \file psThing.h
  * Support for psThings
  */
@@ -186 +186 @@
 } psThing;
 
+/// make a new psThing
 psThing *psThingAlloc(int nthing);
+
+/// free an existing psThing
 void psThingFree(psThing *thing);
 
@@ -486 +489 @@
 
 All globally-visible symbols must be declared in a suitable header
-(.h) file.  Global private symbols (i.e.  those named \code{p_ps})
-should not appear in public header files, but rather in files whose
-names begin \code{p_ps}.
+(.h) file.  Global private symbols should not appear in public header
+files, but rather in separate, private header files.
 
 \subsection{Number Per Line}
@@ -576 +578 @@
 \item 
 Function declarations should be preceeded by a short comment
-describing what the function does.
-
-\tbd{Discuss Doxygen}
+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
@@ -871 +873 @@
 rigid adherence to the guideline.
  
+{ \small 
 \begin{tabular}{lp{3in}p{3in}}
 \textbf{Identifier Type} &
@@ -898 +901 @@
 
 The names of all externally visible functions (i.e. all those that are
-not declared \code{static}) should be verbal phrases, in mixed
-case. The first two characters should be \code{ps}, with the first
-letter of each internal word capitalized.
-
-Functions that are visible at global scope but are not considered part
-of the public interface should be prefixed \code{p_ps}.
-
-Functions that are local to a file should \textit{not} start
-\code{ps} (or \code{p_ps}).
- 
+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}.
+
 &
 
@@ -927 +926 @@
 standard. Non-globally visible words should start with a lowercase
 first letter; Internal words start with capital letters.
-
-Variables visible at global scope should begin with \code{ps},
-or \code{p_ps} if not considered part of the public interface.
-Variables that are local to a file should \textit{not} start
-with \code{ps} (or \code{p_ps}). These variables should be Capitalised
-at the beginning of each word.
 
 Variable names should be short yet meaningful. The choice of a
@@ -943 +936 @@
 
 &
-\code{int i; char c; float myWidth;}\hfil\break
+\code{int i;}\hfil\break
+\code{char c;}\hfil\break
+\code{float myWidth;}\hfil\break
 \hfil\break
 \code{int psNumOTA;}\hfil\break
@@ -959 +954 @@
 enumerated types.
 
-The names of all enumerated types and C-preprocessor symbols (but not
-variables declared \code{const}) declared should start with
-\code{PS_} or \code{P_PS_} and the rest of the name should
-be uppercase with words separated by underscores (\code{_}). In the case of
-system utilities implemented as macros, the names may conform to the
-usual \PS{} conventions (e.g. \code{psAlloc}).
-
 &
 \code{#define PS_MAXLEN 40}\hfil\break
@@ -971 +959 @@
 
 \end{tabular}
+}
 
 %------------------------------------------------------------------------------
@@ -978 +967 @@
 \subsection{When to Make Symbols Global}
 
-Declare all functions and variables \code{static} within a
-file if at all possible (n.b. do not confuse this use of \code{static}
-with its usage to make auto-variables within a function persistent).
+Declare all functions 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.
 
 \subsection{Constants}
@@ -987 +977 @@
 small integers such as -1, 0, and 1 which are permitted to e.g. appear
 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}
@@ -1101 +1124 @@
 
 \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{XXX} in a comment to flag something that is bogus but works.
+Use \code{\warning} in a comment to flag something that is bogus but works.
 
 \item 
-Use \code{FIXME} to flag something that is bogus and broken.
-
-\tbd{Check Doxygen versions of these special comments. I could not
-find any occurrence of \code{@notused@} in the Doxygen documentation}
-\item
-Use \code{NOTREACHED} to indicate a line of code that cannot be reached,
+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}
@@ -1121 +1158 @@
 
 \item 
-Use \code{NOTUSED} to indicate unused arguments to a function:
+Use \code{\notused} to indicate unused arguments to a function:
 e.g.
 \begin{verbatim}
@@ -1133 +1170 @@
 \end{verbatim}
 \end{itemize}
-
-\subsubsection{\label{LAllocFree}10.4.6     Constructors/Destructors}
-
-Type definitions should always be accompanied by prototypes for
-their constructors and destructors:
-
-\begin{itemize}
-\item  The constructor should consist of the type name followed by
-\code{Alloc}; e.g. a type \code{psImage} would
-be created by a function
-\begin{verbatim}
-psImage *psImageAlloc(int nrow, int ncol);
-\end{verbatim}
-
-\item  Similarly, the type should be freed with a destructor named
-\code{typeFree}, e.g.
-\begin{verbatim}
-void psImageFree(psImage *img);
-\end{verbatim}
-
-\item  The constructor should never return \code{NULL}, and
-no code calling the constructor should ever check the return value.
-
-\item  The destructor must not return a value.
-
-\item  The destructor should handle being passed \code{NULL}
-by simply returning immediately. This should not be treated as
-an error condition.
-
-\item  The destructor should call \code{psMemGetRefCounter}; if the value is greater
-  than one, the destructor should simply call \code{psMemDecrRefCounter} and return.
-
-\end{itemize}
-
-\subsection{\label{LConvOps}Naming Conversion Operators}
-
-When defining a function to convert from one type to another, the
-name should be of the form \code{psOldToAlloc}, e.g.\hfil\break
-\code{psEquatorialToEcliptic} (\emph{not} \code{psEquatorial2Ecliptic}).
-
-\subsection{Order of I/O Arguments}
-
-Functions that assign to a variable should list that argument
-\textit{first} (i.e. following the pattern of \code{strcpy}); e.g.
-\begin{verbatim}
-void psAddToVector(restrict psVec *outVec, const restrict psVec *inVec,
-                   int val);
-\end{verbatim}
-
-\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}
 
 %------------------------------------------------------------------------------

trunk/doc/pslib/psLibSRS.tex

@@ -1 @@
-%%% $Id: psLibSRS.tex,v 1.3 2004-04-07 03:26:07 eugene Exp $
+%%% $Id: psLibSRS.tex,v 1.4 2004-04-23 21:57:43 eugene Exp $
 \documentclass[panstarrs]{panstarrs}
 
@@ -77 +77 @@
 \subsubsection{Software Coding Requirements}
 
-\subsubsubsection{CSCI Deliverable}
-
-All final source code generated for the IPP is to be delivered via
-CVS, including the test code.  CVS revision history shall be included
-and made available via CVS.
-
-\subsubsubsection{Languages}
+\paragraph{Languages}
 
 Source code shall be in C.  All source code shall be compiled with
@@ -90 +84 @@
 Scripting language shall be in \tbd{Python, version TBD}. 
 
-\subsubsubsection{Interfaces}
+\paragraph{Interfaces}
 
 Access to low-level Library functions shall be provided via C APIs
@@ -98 +92 @@
 processing jobs shall be available via the UNIX shell.
 
-\subsubsubsection{Coding Standards} 
+\paragraph{Coding Standards} 
 
 The C code shall comply with ANSI Standard C99.  Because the delivered
@@ -110 +104 @@
 defined in the document TBD}.
 
-\subsubsubsection{Commenting and Documentation}
+\paragraph{Naming Conventions}
+
+Header files must have names starting \code{ps} or \code{p_ps} for
+private interface definitions. The latter must appear in a
+subdirectory \code{private} of whichever directory is being searched
+for the public header files.
+
+Functions visible at global scope which are part of the public API
+must have names begining with \code{ps}, and follow the naming
+conventions in the coding standard.  Functions that are visible at
+global scope but which are not part of the public interface must have
+names begining with \code{p_ps}.  Functions that are local to a file
+must \textit{not} start \code{ps} (or \code{p_ps}).
+ 
+Variables visible at global scope which are part of the public API
+must have names begining with \code{ps}, and follow the naming
+conventions in the coding standard.  Variables that are visible at
+global scope but which are not part of the public interface must have
+names begining with \code{p_ps}.  Variables that are local to a file
+must \textit{not} start \code{ps} (or \code{p_ps}).
+
+The names of all enumerated types and C-preprocessor symbols (but not
+variables declared \code{const}) must start with \code{PS_}, in the
+case of public symbols, or \code{P_PS_}, for private symbols.  The
+rest of the name must be uppercase with words separated by underscores
+(\code{_}). An exception is the case of system utilities implemented
+as macros, in which case the names must conform to the convention for
+function names.
+
+When defining a function to convert from one type to another, the name
+should be of the form \code{psOldToAlloc}, e.g.\hfil\break
+\code{psEquatorialToEcliptic} (\emph{not}
+\code{psEquatorial2Ecliptic}).
+
+\paragraph{C Programming Guidelines}
+
+Functions that assign to a variable should list that argument
+\textit{first}, following the pattern of \code{strcpy}; e.g.
+\begin{verbatim}
+void psAddToVector(restrict psVec *outVec, const restrict psVec *inVec,
+                   int val);
+\end{verbatim}
+
+Type definitions should always be accompanied by prototypes for their
+constructors and destructors, following these guidelines:
+
+\begin{itemize}
+\item The constructor name should consist of the type name followed by
+\code{Alloc}; e.g. a type \code{psImage} would be created by a
+function
+\begin{verbatim}
+psImage *psImageAlloc(int nrow, int ncol);
+\end{verbatim}
+
+\item The type should be freed with a destructor named \code{typeFree}, e.g.
+\begin{verbatim}
+void psImageFree(psImage *img);
+\end{verbatim}
+
+\item The constructor must never return \code{NULL}, and no code calling the
+constructor should ever check the return value.
+
+\item The destructor must not return a value.
+
+\item The destructor must handle being passed \code{NULL} by simply
+returning immediately. This should not be treated as an error
+condition.
+
+\item Constructors and Destructors should use the memory reference
+  counter facilities of the PSLib memory management system.
+
+\end{itemize}
+
+\paragraph{Commenting and Documentation}
 
 Commenting of delivered C and Python code shall follow the C and
@@ -124 +191 @@
 documentation shall be delivered as PDF documents.
 
-\subsubsubsection{Version Control}
+\paragraph{Version Control}
 
 Source code version control shall be implemented with CVS.  
 
-\subsubsubsection{Platform architectures and operating systems}
+\paragraph{CSCI Deliverable}
+
+All final source code generated for the IPP is to be delivered via
+CVS, including the test code.  CVS revision history shall be included
+and made available via CVS.
+
+\paragraph{Platform architectures and operating systems}
 
 Makefiles shall be provided with appropriate flags set so that all
@@ -143 +216 @@
 such as those caused by lex-generated code.  
 
-Although the code must compile successfully under all three listed
+Although the code must compile successfully under both listed
 operating systems, unit testing should only be performed for the
 x86/Linux combination.
 
-\subsubsubsection{Software Configuration}
+\paragraph{Software Configuration}
 
 \tbd{deferred}