Changeset 501
- Timestamp:
- Apr 22, 2004, 10:30:32 AM (22 years ago)
- File:
-
- 1 edited
-
trunk/doc/misc/codeConventions.tex (modified) (20 diffs)
Legend:
- Unmodified
- Added
- Removed
-
trunk/doc/misc/codeConventions.tex
r391 r501 1 %%% $Id: codeConventions.tex,v 1.1 2 2004-04-07 03:26:07eugene Exp $1 %%% $Id: codeConventions.tex,v 1.13 2004-04-22 20:30:32 eugene Exp $ 2 2 \documentclass[panstarrs]{panstarrs} 3 3 … … 78 78 (\code{http://java.sun.com/docs/codeconv/}) for more details. 79 79 80 Such an adaption is isexplicitly permitted by the Sun Microsystems80 Such an adaption is explicitly permitted by the Sun Microsystems 81 81 copyright notice (Copyright.doc.html). 82 82 … … 103 103 header files & \code{.h} \\ 104 104 SWIG interface files & \code{.i} \\ 105 Perl files & \code{.pl} \\ 106 Python files & \code{.py} \\ 105 107 \end{tabular} 106 108 \end{center} … … 141 143 \subsubsection{Include Files} 142 144 143 Header files should have names starting \code{ps} or144 \code{p_ps} for private interface definitions. The latter145 should appear in a subdirectory \code{Private} of whichever146 directory is being searched for the public header files.147 148 145 Include files should have the following order: 149 146 \begin{itemize} 147 \item 148 A brief description of the functionality provided by this set of APIs. 149 This comment should not duplicate information available 150 elsewhere (e.g. the filename; log information available from cvs). 151 150 152 \item 151 153 A check for the existance of a CPP symbol of the form … … 154 156 155 157 \item 156 A brief description of the functionality provided by this set of APIs. 157 This comment should not duplicate information available 158 elsewhere (e.g. the filename; log information available from cvs). 158 Any \code{#define}d constants. {\bf Note:} \code{#define} should be used rather 159 than e.g. \code{const int}; C and C++ const semantics are different. 159 160 160 161 \item 161 Any \code{#define}d constants. N.b. \code{#define} should be used rather 162 than e.g. \code{const int}; C and C++ const semantics are different. 162 Any enums. 163 163 164 164 \item 165 Any typedefs .165 Any typedefs and structs. 166 166 167 167 \item … … 171 171 e.g. for file \file{psThing.h}: 172 172 \begin{verbatim} 173 #if !defined(PS_THING_H)174 #define PS_THING_H175 173 /* 176 174 * Support for psThings 177 175 */ 178 #define PS_NMAX 10 /* maximum number of subthings */ 179 176 177 #if !defined(PS_THING_H) 178 #define PS_THING_H 179 180 #define PS_NMAX 10 // maximum number of subthings 181 182 enum {PS_FIRST, PS_SECOND, PS_THRID}; // subthing sequences 180 183 typedef struct { 181 int nthing; / * number of subthings */182 int sthing[PS_NMAX]; / * the subthings */184 int nthing; // number of subthings 185 int sthing[PS_NMAX]; // the subthings 183 186 } psThing; 184 187 … … 188 191 #endif 189 192 \end{verbatim} 193 \tbd{add doxygen comments to this example} 190 194 191 195 \subsubsection{C Source Files} … … 220 224 \section{Indentation} 221 225 222 Four spaces should be used as the unit of indentation. The exact223 construction of the indentation (spaces vs. tabs) is unspecified. Tabs224 must be set exactly every 8 spaces (not 4).226 Four spaces should be used as the unit of indentation. Spaces are 227 recommended over tabs for indentation, but if tabs are used, the tabs 228 stops must be set to 8 spaces, not 4. 225 229 226 230 \subsection{Line Length} 227 231 228 Avoid lines longer than 110 characters , since they're not handled well by many terminals and tools.232 Avoid lines longer than 110 characters. 229 233 230 234 When preparing documents, you should ensure that lines of this length 231 are not wrapped (If you are using the standard PSDC \LaTeX{} class232 file \file{panstarrs.cls}, \CODE|\begin{verbatim} ... \end{verbatim}| 233 will do this for you).235 are not wrapped\footnote{If you are using the standard PSDC \LaTeX{} 236 class file \file{panstarrs.cls}, \CODE|\begin{verbatim} 237 ... \end{verbatim}| will do this for you}. 234 238 235 239 \subsection{Wrapping Lines} … … 252 256 253 257 \item Align the new line with the beginning of the expression at the 254 same level on the previous line (for emacs users, this means the 255 indentation that \code{<tab>} produces. If this isn't helpful to 256 the majority of the people writing code for \PS{}, we can 257 be more formal about what this rule means). 258 same level on the previous line\footnote{For emacs users, this means 259 the indentation that \code{<tab>} produces}. 258 260 259 261 \item If the above rules lead to confusing code or to code that's 260 squished up against the right margin, just indent 8 spaces instead. 261 This should be \emph{very} rare! Consider whether you should be 262 e.g. factoring code into a function. 262 squished up against the right margin, just indent 8 spaces 263 instead.\footnote{This should be \emph{very} rare! Consider whether 264 you should be e.g. factoring code into a function.} 265 263 266 \end{itemize} 264 267 … … 300 303 } 301 304 302 //INDENT 4SPACES TO AVOID VERY DEEP INDENTS305 //INDENT 8 SPACES TO AVOID VERY DEEP INDENTS 303 306 static type honkingLongFunctionName( 304 int anArg,305 Object anotherArg, String yetAnotherArg,306 Object andStillAnother)307 int anArg, 308 Object anotherArg, String yetAnotherArg, 309 Object andStillAnother) 307 310 { 308 311 ... … … 400 403 401 404 \subsubsection{Trailing Comments} 405 \label{col40} 402 406 403 407 Very short comments can appear on the same line as the code they 404 describe, and should be indented to column 40 (in emacs, this405 may be achieved with \code{ESC;} ). If the code extends beyond406 this column, the comment should be separated from the closing semi-colon 407 bya single space.408 describe, and should be indented to column 40\footnote{In emacs, this 409 may be achieved with \code{ESC;}}. If the code extends beyond this 410 column, the comment should be separated from the closing semi-colon by 411 a single space. 408 412 409 413 Here's an example of a trailing comment in C code: … … 479 483 \end{verbatim} 480 484 481 (Note that the comments are indented to column 40 ).485 (Note that the comments are indented to column 40, as per section~\ref{col40}). 482 486 483 487 \subsection{Initialization} … … 572 576 573 577 \begin{verbatim} 574 void find_neos(const REGION *sky, // bregion to search 575 const char *descrip // work orders 576 ) 578 void find_neos(const REGION *sky, const char *descrip) 577 579 { 578 580 struct { … … 717 719 \subsection{switch Statements} 718 720 719 A \code{switch} statement should have the following form (note the 720 indentation; the \code{case/default} is indented 2 spaces, the 721 other statements are at the usual 4 space indent): 721 A \code{switch} statement should have the following form): 722 722 \begin{verbatim} 723 723 switch (condition) { 724 case ABC:725 statements;726 /* falls through */727 728 case DEF:729 case GHI:730 statements;731 break;732 733 case XYZ:734 statements;735 break;736 737 default:738 statements;739 break;724 case ABC: 725 statements; 726 /* falls through */ 727 728 case DEF: 729 case GHI: 730 statements; 731 break; 732 733 case XYZ: 734 statements; 735 break; 736 737 default: 738 statements; 739 break; 740 740 } 741 741 \end{verbatim} … … 756 756 added (not all compilers diagnose missing elements). In this case, 757 757 the action in the default clause should be to generate an error 758 and abort. 758 \and abort. 759 760 \subsection{label Statements} 761 762 Code labels should be indented to align with the previous level of 763 indentation. 759 764 760 765 %------------------------------------------------------------------------------ … … 799 804 800 805 \item 801 Low priority binary operators (\code{+} and \code{-} and below) 802 should be separated from their operands by spaces; higher 803 precedence operators (e.g. \code{*}, \code{/}, \code{%}, 804 \code{.} and \code{->}) should not be separated by spaces. 805 Blank spaces should never separate 806 unary operators such as a type cast, unary minus, increment 807 (\code{++}), and decrement (\code{--}) from their operands. Examples: 806 Binary operators should be separated from their operands by spaces. 807 Blank spaces should never separate unary operators such as a type 808 cast, unary minus, increment (\code{++}), and decrement (\code{--}) 809 from their operands. Examples: 808 810 \begin{verbatim} 809 811 a += c + d; 810 a = (a + b) /(c*d);812 a = (a + b) / (c * d); 811 813 812 814 while (*d++ = *s++) { // Tricky way of copying until '\0' 813 815 n++; 814 816 } 815 printf ("size is %d\n", foo);817 printf ("size is %d\n", foo); 816 818 \end{verbatim} 817 819 … … 835 837 easier to read. They can also give information about the function of 836 838 the identifier -- for example, whether it's a constant, a function, or 837 a type -- which can be helpful in understanding the code. 839 a type -- which can be helpful in understanding the code. Remember 840 these are guidelines for improving readability; clarity should trump 841 rigid adherence to the guideline. 838 842 839 843 \begin{tabular}{lp{3in}p{3in}} … … 845 849 846 850 Type names should be nouns, in mixed case with the first letter of 847 each internal word capitalized. 851 each internal word capitalized. Little words, such as 'for', 'to', 852 'at', etc, may be written in all lower-case or separated with 853 underscores if it makes the name clearer. 848 854 849 855 If and only if the type is visible at global scope, the … … 1159 1165 \end{verbatim} 1160 1166 1161 \textit{ N.b. compilers are free to ignore the \code{restrict} keyword,1162 so all code should be written to explicitly handle aliasing}.1167 \textit{{\bf Note:} compilers are free to ignore the \code{restrict} 1168 keyword, so all code should be written to explicitly handle aliasing}. 1163 1169 1164 1170 \subsection{structs and typedefs} … … 1438 1444 \end{verbatim} 1439 1445 1440 \bibliographystyle{plain} 1446 \section{How to Achieve This Style with Astyle} 1447 \label{astyle} 1448 1449 The purpose of a coding standard is to improve coding efficiency, not 1450 to hinder it. Since people are inherently falible, 100\% adherence to 1451 the standard is an impossible goal for human-generated code. 1452 Furthermore, laziness and slopiness are human nature. To minimize the 1453 amount of effort spent in keeping software in line with a coding 1454 standard is to use automatic re-formatting tools to enforce the 1455 standard. Various software tools exist to perform these tasks. One 1456 of these is \code{astyle}, an open-source tool which takes a variety 1457 of options which allow the use to tailor the coding standard to suit 1458 their preferences. We have determined the following collection of 1459 astyle options which achieve the many of the coding standard 1460 guidelines specified above. Note that any of the listed options 1461 (always in the 'long' form) may be specified in the user's 1462 \code{.astylerc} file by dropping the leading dash. 1463 1464 \begin{itemize} 1465 \item \code{--mode=c} - This option tells \code{astyle} to recognize 1466 the source code as C code. 1467 1468 \item \code{--indent-switches} - This option tells \code{astyle} to 1469 indent the \code{case} statements in a \code{switch}. Do not also 1470 specify \code{--indent-cases}. 1471 1472 \item \code{--indent-labels} - This option tells \code{astyle} to add 1473 indentation to labels so they are indented one level less than the 1474 current level. 1475 1476 \item \code{--min-conditional-indent=0} - This option tells 1477 \code{astyle} not to add indentation to successive lines of 1478 multiple-line conditional statements. 1479 1480 \item \code{--max-instatement-indent=20} - This option tells 1481 \code{astyle} to limit the total amount of indentation to 20 spaces. 1482 1483 \item \code{--pad=oper} - This option tells \code{astyle} to add 1484 padding about binary operators. 1485 1486 \item \code{--brackets=break} - This option tells \code{astyle} to 1487 break brackets from their pre-block statements, dropping them to the 1488 next line. 1489 1490 \item \code{--convert-tabs} - This option tells \code{astyle} to 1491 convert tabs into the equivalent number of space characters. 1492 1493 \item \code{--indent=spaces=4} - This option tells \code{astyle} to 1494 use 4 spaces per indent level. 1495 1496 bibliographystyle{plain} 1441 1497 \bibliography{panstarrs} 1442 1498
Note:
See TracChangeset
for help on using the changeset viewer.
