Changeset 165 for trunk/doc/misc/codeConventions.tex

Timestamp:

Mar 9, 2004, 2:47:24 PM (22 years ago)

Author:

rhl

Message:

1/ Relaxed rule about always using parens
2/ Changed \XXX to \TBD (from panstarrs.def)
3/ Changed New/Del to Alloc/Free

File:

• trunk/doc/misc/codeConventions.tex (modified) (18 diffs)

trunk/doc/misc/codeConventions.tex

@@ -17 +17 @@
 
 \newcommand{\matchBracket}[1]{}         % help emacs match properly
-\newcommand{\XXX}[1]{{\color{red} XXX #1\hfil\break}}
 
 \pagenumbering{roman} \thispagestyle{empty} \maketitle
@@ -195 +194 @@
 } psThing;
 
-psThing *psThingNew(int nthing);
-void psThingDel(psThing *thing);
+psThing *psThingAlloc(int nthing);
+void psThingFree(psThing *thing);
 
 #endif
@@ -226 +225 @@
 \subsubsection{SWIG Interface Files}
 
-\XXX{Write me}
+\TBD{Write me}
 
 %------------------------------------------------------------------------------
@@ -448 +447 @@
 \label{DocComments} 
 
-\XXX{Need references to Doxygen here.}
+\TBD{Need references to Doxygen here.}
 
 If you need to give information about a type, interface, or variable
@@ -555 +554 @@
 describing what the function does.
 
-\XXX{Discuss Doxygen}
+\TBD{Discuss Doxygen}
 
 \item The function's type should appear on the same line as the
@@ -1006 +1005 @@
 problems. Even if the operator precedence seems clear to you, it might
 not be to others-you shouldn't assume that other programmers know
-precedence as well as you do.
-
-\begin{verbatim}
-if (a == b && c == d)                   // AVOID!
-if ((a == b) && (c == d))               // RIGHT
+precedence as well as you do. In cases where the precedence rules
+are clear, the parentheses may be omitted.
+
+\begin{verbatim}
+if (a & b || c & d)                     // AVOID!
+if ((a & b) || (c & d))                 // RIGHT
 \end{verbatim}
 
@@ -1083 +1083 @@
 Use \code{FIXME} to flag something that is bogus and broken.
 
-\XXX{Check Doxygen versions of these special comments. I could not
+\TBD{Check Doxygen versions of these special comments. I could not
 find any occurrence of \code{@notused@} in the Doxygen documentation}
-\item 
+\item
 Use \code{NOTREACHED} to indicate a line of code that cannot be reached,
 e.g.
@@ -1109 +1109 @@
 \end{itemize}
 
-\subsubsection{\label{LNewDel}10.4.6     Constructors/Destructors}
+\subsubsection{\label{LAllocFree}10.4.6     Constructors/Destructors}
 
 Type definitions should always be accompanied by prototypes for
@@ -1116 +1116 @@
 \begin{itemize}
 \item  The constructor should consist of the type name followed by
-\code{New}; e.g. a type \code{psImage} would
+\code{Alloc}; e.g. a type \code{psImage} would
 be created by a function
 \begin{verbatim}
-psImage *psImageNew(int nrow, int ncol);
+psImage *psImageAlloc(int nrow, int ncol);
 \end{verbatim}
 
 \item  Similarly, the type should be freed with a destructor named
-\code{typeDel}, e.g.
-\begin{verbatim}
-void psImageDel(psImage *img);
+\code{typeFree}, e.g.
+\begin{verbatim}
+void psImageFree(psImage *img);
 \end{verbatim}
 
@@ -1137 +1137 @@
 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}
 
@@ -1142 +1145 @@
 
 When defining a function to convert from one type to another, the
-name should be of the form \code{psOldToNew}, e.g.\hfil\break
+name should be of the form \code{psOldToAlloc}, e.g.\hfil\break
 \code{psEquatorialToEcliptic} (\emph{not} \code{psEquatorial2Ecliptic}).
 
@@ -1195 +1198 @@
 \label{SourceExample} 
 
-\XXX{Need to include more of the rules, and shorten the example}
+\TBD{Need to include more of the rules, and shorten the example}
 Here's \file{psBuffer.h}:
 \begin{verbatim}
@@ -1207 +1210 @@
 } psBuffer;
 
-psBuffer *psBufferNew(void);
-void psBufferDel(psBuffer *buf,         // buffer to delete
+psBuffer *psBufferAlloc(void);
+void psBufferFree(psBuffer *buf,         // buffer to delete
                  int deep);             // NOTUSED. Do a deep delete
 
@@ -1243 +1246 @@
  * Create/destroy psBuffers
  */
-psBuffer *psBufferNew(void)
+psBuffer *psBufferAlloc(void)
 {
     psBuffer *buf = psAlloc(sizeof(psBuffer));
@@ -1251 +1254 @@
 }
 
-void psBufferDel(psBuffer *buf,         // buffer to delete
+void psBufferFree(psBuffer *buf,         // buffer to delete
                  int deep)              // NOTUSED. Do a deep delete
 {
@@ -1291 +1294 @@
 int main(void)
 {
-    buf = psBufferNew();
+    buf = psBufferAlloc();
     long t;                               // current time
 
@@ -1305 +1308 @@
     psBufferAppend(buf, getNewline(NL));
 
-    psBufferDel(buf, 0);
+    psBufferFree(buf, 0);
 
     return 0;
@@ -1402 +1405 @@
   The line-length limit has been changed from 80 to 110 characters.
 
+\item
+  Relaxed wording to allow parentheses to be omitted when the precedence
+  is well known and unambiguous.
+
 \end{itemize}