Changeset 514 for trunk/doc/pslib/psLibSRS.tex

Timestamp:

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

Author:

eugene

Message:

changes to coding requirements from MHPCC comments

File:

• trunk/doc/pslib/psLibSRS.tex (modified) (7 diffs)

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}