Changeset 514 for trunk/doc/design/specs.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/design/specs.tex (modified) (6 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}