Index: /trunk/doc/misc/codeConventions.tex =================================================================== --- /trunk/doc/misc/codeConventions.tex (revision 500) +++ /trunk/doc/misc/codeConventions.tex (revision 501) @@ -1,3 +1,3 @@ -%%% $Id: codeConventions.tex,v 1.12 2004-04-07 03:26:07 eugene Exp $ +%%% $Id: codeConventions.tex,v 1.13 2004-04-22 20:30:32 eugene Exp $ \documentclass[panstarrs]{panstarrs} @@ -78,5 +78,5 @@ (\code{http://java.sun.com/docs/codeconv/}) for more details. -Such an adaption is is explicitly permitted by the Sun Microsystems +Such an adaption is explicitly permitted by the Sun Microsystems copyright notice (Copyright.doc.html). @@ -103,4 +103,6 @@ header files & \code{.h} \\ SWIG interface files & \code{.i} \\ +Perl files & \code{.pl} \\ +Python files & \code{.py} \\ \end{tabular} \end{center} @@ -141,11 +143,11 @@ \subsubsection{Include Files} -Header files should have names starting \code{ps} or -\code{p_ps} for private interface definitions. The latter -should appear in a subdirectory \code{Private} of whichever -directory is being searched for the public header files. - Include files should have the following order: \begin{itemize} +\item +A brief description of the functionality provided by this set of APIs. +This comment should not duplicate information available +elsewhere (e.g. the filename; log information available from cvs). + \item A check for the existance of a CPP symbol of the form @@ -154,14 +156,12 @@ \item -A brief description of the functionality provided by this set of APIs. -This comment should not duplicate information available -elsewhere (e.g. the filename; log information available from cvs). +Any \code{#define}d constants. {\bf Note:} \code{#define} should be used rather +than e.g. \code{const int}; C and C++ const semantics are different. \item -Any \code{#define}d constants. N.b. \code{#define} should be used rather -than e.g. \code{const int}; C and C++ const semantics are different. +Any enums. \item -Any typedefs. +Any typedefs and structs. \item @@ -171,14 +171,17 @@ e.g. for file \file{psThing.h}: \begin{verbatim} -#if !defined(PS_THING_H) -#define PS_THING_H /* * Support for psThings */ -#define PS_NMAX 10 /* maximum number of subthings */ - + +#if !defined(PS_THING_H) +#define PS_THING_H + +#define PS_NMAX 10 // maximum number of subthings + +enum {PS_FIRST, PS_SECOND, PS_THRID}; // subthing sequences typedef struct { - int nthing; /* number of subthings */ - int sthing[PS_NMAX]; /* the subthings */ + int nthing; // number of subthings + int sthing[PS_NMAX]; // the subthings } psThing; @@ -188,4 +191,5 @@ #endif \end{verbatim} +\tbd{add doxygen comments to this example} \subsubsection{C Source Files} @@ -220,16 +224,16 @@ \section{Indentation} -Four spaces should be used as the unit of indentation. The exact -construction of the indentation (spaces vs. tabs) is unspecified. Tabs -must be set exactly every 8 spaces (not 4). +Four spaces should be used as the unit of indentation. Spaces are +recommended over tabs for indentation, but if tabs are used, the tabs +stops must be set to 8 spaces, not 4. \subsection{Line Length} -Avoid lines longer than 110 characters, since they're not handled well by many terminals and tools. +Avoid lines longer than 110 characters. When preparing documents, you should ensure that lines of this length -are not wrapped (If you are using the standard PSDC \LaTeX{} class -file \file{panstarrs.cls}, \CODE|\begin{verbatim} ... \end{verbatim}| -will do this for you). +are not wrapped\footnote{If you are using the standard PSDC \LaTeX{} +class file \file{panstarrs.cls}, \CODE|\begin{verbatim} +... \end{verbatim}| will do this for you}. \subsection{Wrapping Lines} @@ -252,13 +256,12 @@ \item Align the new line with the beginning of the expression at the -same level on the previous line (for emacs users, this means the -indentation that \code{} produces. If this isn't helpful to -the majority of the people writing code for \PS{}, we can -be more formal about what this rule means). +same level on the previous line\footnote{For emacs users, this means +the indentation that \code{} produces}. \item If the above rules lead to confusing code or to code that's -squished up against the right margin, just indent 8 spaces instead. -This should be \emph{very} rare! Consider whether you should be -e.g. factoring code into a function. +squished up against the right margin, just indent 8 spaces +instead.\footnote{This should be \emph{very} rare! Consider whether +you should be e.g. factoring code into a function.} + \end{itemize} @@ -300,9 +303,9 @@ } -//INDENT 4 SPACES TO AVOID VERY DEEP INDENTS +//INDENT 8 SPACES TO AVOID VERY DEEP INDENTS static type honkingLongFunctionName( - int anArg, - Object anotherArg, String yetAnotherArg, - Object andStillAnother) + int anArg, + Object anotherArg, String yetAnotherArg, + Object andStillAnother) { ... @@ -400,10 +403,11 @@ \subsubsection{Trailing Comments} +\label{col40} Very short comments can appear on the same line as the code they -describe, and should be indented to column 40 (in emacs, this -may be achieved with \code{ESC;}). If the code extends beyond -this column, the comment should be separated from the closing semi-colon -by a single space. +describe, and should be indented to column 40\footnote{In emacs, this +may be achieved with \code{ESC;}}. If the code extends beyond this +column, the comment should be separated from the closing semi-colon by +a single space. Here's an example of a trailing comment in C code: @@ -479,5 +483,5 @@ \end{verbatim} -(Note that the comments are indented to column 40). +(Note that the comments are indented to column 40, as per section~\ref{col40}). \subsection{Initialization} @@ -572,7 +576,5 @@ \begin{verbatim} -void find_neos(const REGION *sky, // bregion to search - const char *descrip // work orders - ) +void find_neos(const REGION *sky, const char *descrip) { struct { @@ -717,25 +719,23 @@ \subsection{switch Statements} -A \code{switch} statement should have the following form (note the -indentation; the \code{case/default} is indented 2 spaces, the -other statements are at the usual 4 space indent): +A \code{switch} statement should have the following form): \begin{verbatim} switch (condition) { - case ABC: - statements; - /* falls through */ - - case DEF: - case GHI: - statements; - break; - - case XYZ: - statements; - break; - - default: - statements; - break; + case ABC: + statements; + /* falls through */ + + case DEF: + case GHI: + statements; + break; + + case XYZ: + statements; + break; + + default: + statements; + break; } \end{verbatim} @@ -756,5 +756,10 @@ added (not all compilers diagnose missing elements). In this case, the action in the default clause should be to generate an error -and abort. +\and abort. + +\subsection{label Statements} + +Code labels should be indented to align with the previous level of +indentation. %------------------------------------------------------------------------------ @@ -799,19 +804,16 @@ \item - Low priority binary operators (\code{+} and \code{-} and below) -should be separated from their operands by spaces; higher -precedence operators (e.g. \code{*}, \code{/}, \code{%}, - \code{.} and \code{->}) should not be separated 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: +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); + a = (a + b) / (c * d); while (*d++ = *s++) { // Tricky way of copying until '\0' n++; } - printf("size is %d\n", foo); + printf ("size is %d\n", foo); \end{verbatim} @@ -835,5 +837,7 @@ easier to read. They can also give information about the function of the identifier -- for example, whether it's a constant, a function, or -a type -- which can be helpful in understanding the code. +a type -- which can be helpful in understanding the code. Remember +these are guidelines for improving readability; clarity should trump +rigid adherence to the guideline. \begin{tabular}{lp{3in}p{3in}} @@ -845,5 +849,7 @@ Type names should be nouns, in mixed case with the first letter of -each internal word capitalized. +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 @@ -1159,6 +1165,6 @@ \end{verbatim} -\textit{N.b. compilers are free to ignore the \code{restrict} keyword, -so all code should be written to explicitly handle aliasing}. +\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} @@ -1438,5 +1444,55 @@ \end{verbatim} -\bibliographystyle{plain} +\section{How to Achieve This Style with Astyle} +\label{astyle} + +The purpose of a coding standard is to improve coding efficiency, not +to hinder it. Since people are inherently falible, 100\% adherence to +the standard is an impossible goal for human-generated code. +Furthermore, laziness and slopiness are human nature. To minimize the +amount of effort spent in keeping software in line with a coding +standard is to use automatic re-formatting tools to enforce the +standard. Various software tools exist to perform these tasks. One +of these is \code{astyle}, an open-source tool which takes a variety +of options which allow the use to tailor the coding standard to suit +their preferences. We have determined the following collection of +astyle options which achieve the many of the coding standard +guidelines specified above. Note that any of the listed options +(always in the 'long' form) may be specified in the user's +\code{.astylerc} file by dropping the leading dash. + +\begin{itemize} +\item \code{--mode=c} - This option tells \code{astyle} to recognize + the source code as C code. + +\item \code{--indent-switches} - This option tells \code{astyle} to + indent the \code{case} statements in a \code{switch}. Do not also + specify \code{--indent-cases}. + +\item \code{--indent-labels} - This option tells \code{astyle} to add + indentation to labels so they are indented one level less than the + current level. + +\item \code{--min-conditional-indent=0} - This option tells + \code{astyle} not to add indentation to successive lines of + multiple-line conditional statements. + +\item \code{--max-instatement-indent=20} - This option tells + \code{astyle} to limit the total amount of indentation to 20 spaces. + +\item \code{--pad=oper} - This option tells \code{astyle} to add + padding about binary operators. + +\item \code{--brackets=break} - This option tells \code{astyle} to + break brackets from their pre-block statements, dropping them to the + next line. + +\item \code{--convert-tabs} - This option tells \code{astyle} to + convert tabs into the equivalent number of space characters. + +\item \code{--indent=spaces=4} - This option tells \code{astyle} to + use 4 spaces per indent level. + +bibliographystyle{plain} \bibliography{panstarrs}