Changeset 514 for trunk/doc/misc/codeConventions.tex
- Timestamp:
- Apr 23, 2004, 11:57:43 AM (22 years ago)
- File:
-
- 1 edited
-
trunk/doc/misc/codeConventions.tex (modified) (16 diffs)
Legend:
- Unmodified
- Added
- Removed
-
trunk/doc/misc/codeConventions.tex
r505 r514 1 %%% $Id: codeConventions.tex,v 1.1 4 2004-04-22 22:33:38 price Exp $1 %%% $Id: codeConventions.tex,v 1.15 2004-04-23 21:57:43 eugene Exp $ 2 2 \documentclass[panstarrs]{panstarrs} 3 3 … … 171 171 e.g. for file \file{psThing.h}: 172 172 \begin{verbatim} 173 /* 173 /** \file psThing.h 174 174 * Support for psThings 175 175 */ … … 186 186 } psThing; 187 187 188 /// make a new psThing 188 189 psThing *psThingAlloc(int nthing); 190 191 /// free an existing psThing 189 192 void psThingFree(psThing *thing); 190 193 … … 486 489 487 490 All globally-visible symbols must be declared in a suitable header 488 (.h) file. Global private symbols (i.e. those named \code{p_ps}) 489 should not appear in public header files, but rather in files whose 490 names begin \code{p_ps}. 491 (.h) file. Global private symbols should not appear in public header 492 files, but rather in separate, private header files. 491 493 492 494 \subsection{Number Per Line} … … 576 578 \item 577 579 Function declarations should be preceeded by a short comment 578 describing what the function does. 579 580 \tbd{Discuss Doxygen} 580 describing what the function does. These comment blocks should 581 include doxygen-style comments to provide a brief desription as well 582 as other warnings, bugs, etc as needed. 581 583 582 584 \item The function's type should appear on the same line as the … … 871 873 rigid adherence to the guideline. 872 874 875 { \small 873 876 \begin{tabular}{lp{3in}p{3in}} 874 877 \textbf{Identifier Type} & … … 898 901 899 902 The names of all externally visible functions (i.e. all those that are 900 not declared \code{static}) should be verbal phrases, in mixed 901 case. The first two characters should be \code{ps}, with the first 902 letter of each internal word capitalized. 903 904 Functions that are visible at global scope but are not considered part 905 of the public interface should be prefixed \code{p_ps}. 906 907 Functions that are local to a file should \textit{not} start 908 \code{ps} (or \code{p_ps}). 909 903 not declared \code{static}) should be verbal phrases, in mixed case. 904 905 Namespaces should be protected by using special naming prefixes to 906 restrict the name space in particular libraries. For example, the 907 PSLib functions are all prefixed with \code{ps}. 908 910 909 & 911 910 … … 927 926 standard. Non-globally visible words should start with a lowercase 928 927 first letter; Internal words start with capital letters. 929 930 Variables visible at global scope should begin with \code{ps},931 or \code{p_ps} if not considered part of the public interface.932 Variables that are local to a file should \textit{not} start933 with \code{ps} (or \code{p_ps}). These variables should be Capitalised934 at the beginning of each word.935 928 936 929 Variable names should be short yet meaningful. The choice of a … … 943 936 944 937 & 945 \code{int i; char c; float myWidth;}\hfil\break 938 \code{int i;}\hfil\break 939 \code{char c;}\hfil\break 940 \code{float myWidth;}\hfil\break 946 941 \hfil\break 947 942 \code{int psNumOTA;}\hfil\break … … 959 954 enumerated types. 960 955 961 The names of all enumerated types and C-preprocessor symbols (but not962 variables declared \code{const}) declared should start with963 \code{PS_} or \code{P_PS_} and the rest of the name should964 be uppercase with words separated by underscores (\code{_}). In the case of965 system utilities implemented as macros, the names may conform to the966 usual \PS{} conventions (e.g. \code{psAlloc}).967 968 956 & 969 957 \code{#define PS_MAXLEN 40}\hfil\break … … 971 959 972 960 \end{tabular} 961 } 973 962 974 963 %------------------------------------------------------------------------------ … … 978 967 \subsection{When to Make Symbols Global} 979 968 980 Declare all functions and variables \code{static} within a 981 file if at all possible (n.b. do not confuse this use of \code{static} 982 with its usage to make auto-variables within a function persistent). 969 Declare all functions and top-level variables \code{static} within a 970 file if they are not needed outside of the file. {\bf Note:} do not 971 confuse this use of \code{static} with its usage to make 972 auto-variables within a function persistent. 983 973 984 974 \subsection{Constants} … … 987 977 small integers such as -1, 0, and 1 which are permitted to e.g. appear 988 978 in a \code{for} loop as counter values. 979 980 \subsection{Type Qualifiers (const and restrict)} 981 982 All interfaces and type definitions should use \code{const} and 983 \code{restrict} wherever appropriate. For example, 984 \begin{verbatim} 985 typedef struct { 986 int n; 987 float *restrict vec; 988 } psVec; 989 990 psVec *psVecAdd(const restrict* psVec s1, const restrict* psVec s2); 991 \end{verbatim} 992 993 \textit{{\bf Note:} compilers are free to ignore the \code{restrict} 994 keyword, so all code should be written to explicitly handle aliasing}. 995 996 \subsection{structs and typedefs} 997 998 All structs should be defined as \code{typedef}s. 999 1000 A struct should not include a struct 1001 tag unless it's self-referential; E.g. 1002 \begin{verbatim} 1003 typedef struct myStruct { // Omit "myStruct" 1004 int x; 1005 } myStruct; 1006 1007 typedef struct yourStruct { // OK 1008 struct yourStruct *next; 1009 int x; 1010 } yourStruct; 1011 \end{verbatim} 989 1012 990 1013 \subsection{Variable Assignments} … … 1101 1124 1102 1125 \subsubsection{Special Comments} 1126 1127 Doxygen has special comments which are used to provide specific notes 1128 in the code. These are added in as special entries and sections in 1129 the Doxygen-generated documentation. These special comments should be 1130 used in addition to the Doxygen usage to make these types of 1131 conditions easily searchable. 1132 1103 1133 \begin{itemize} 1104 1134 \item 1105 Use \code{ XXX} in a comment to flag something that is bogus but works.1135 Use \code{\warning} in a comment to flag something that is bogus but works. 1106 1136 1107 1137 \item 1108 Use \code{FIXME} to flag something that is bogus and broken. 1109 1110 \tbd{Check Doxygen versions of these special comments. I could not 1111 find any occurrence of \code{@notused@} in the Doxygen documentation} 1112 \item 1113 Use \code{NOTREACHED} to indicate a line of code that cannot be reached, 1138 Use \code{\bug} to flag something that is bogus and broken. 1139 1140 \item 1141 Use \code{\todo} to note additional work to be done 1142 1143 \item 1144 Use \code{\note} to make other general notes 1145 1146 \item 1147 Use \code{\test} to list test cases 1148 1149 \item 1150 Use \code{\notreached} to indicate a line of code that cannot be reached, 1114 1151 e.g. 1115 1152 \begin{verbatim} … … 1121 1158 1122 1159 \item 1123 Use \code{ NOTUSED} to indicate unused arguments to a function:1160 Use \code{\notused} to indicate unused arguments to a function: 1124 1161 e.g. 1125 1162 \begin{verbatim} … … 1133 1170 \end{verbatim} 1134 1171 \end{itemize} 1135 1136 \subsubsection{\label{LAllocFree}10.4.6 Constructors/Destructors}1137 1138 Type definitions should always be accompanied by prototypes for1139 their constructors and destructors:1140 1141 \begin{itemize}1142 \item The constructor should consist of the type name followed by1143 \code{Alloc}; e.g. a type \code{psImage} would1144 be created by a function1145 \begin{verbatim}1146 psImage *psImageAlloc(int nrow, int ncol);1147 \end{verbatim}1148 1149 \item Similarly, the type should be freed with a destructor named1150 \code{typeFree}, e.g.1151 \begin{verbatim}1152 void psImageFree(psImage *img);1153 \end{verbatim}1154 1155 \item The constructor should never return \code{NULL}, and1156 no code calling the constructor should ever check the return value.1157 1158 \item The destructor must not return a value.1159 1160 \item The destructor should handle being passed \code{NULL}1161 by simply returning immediately. This should not be treated as1162 an error condition.1163 1164 \item The destructor should call \code{psMemGetRefCounter}; if the value is greater1165 than one, the destructor should simply call \code{psMemDecrRefCounter} and return.1166 1167 \end{itemize}1168 1169 \subsection{\label{LConvOps}Naming Conversion Operators}1170 1171 When defining a function to convert from one type to another, the1172 name should be of the form \code{psOldToAlloc}, e.g.\hfil\break1173 \code{psEquatorialToEcliptic} (\emph{not} \code{psEquatorial2Ecliptic}).1174 1175 \subsection{Order of I/O Arguments}1176 1177 Functions that assign to a variable should list that argument1178 \textit{first} (i.e. following the pattern of \code{strcpy}); e.g.1179 \begin{verbatim}1180 void psAddToVector(restrict psVec *outVec, const restrict psVec *inVec,1181 int val);1182 \end{verbatim}1183 1184 \subsection{Type Qualifiers (const and restrict)}1185 1186 All interfaces and type definitions should use \code{const} and1187 \code{restrict} wherever appropriate. For example,1188 \begin{verbatim}1189 typedef struct {1190 int n;1191 float *restrict vec;1192 } psVec;1193 1194 psVec *psVecAdd(const restrict* psVec s1, const restrict* psVec s2);1195 \end{verbatim}1196 1197 \textit{{\bf Note:} compilers are free to ignore the \code{restrict}1198 keyword, so all code should be written to explicitly handle aliasing}.1199 1200 \subsection{structs and typedefs}1201 1202 All structs should be defined as \code{typedef}s.1203 1204 A struct should not include a struct1205 tag unless it's self-referential; E.g.1206 \begin{verbatim}1207 typedef struct myStruct { // Omit "myStruct"1208 int x;1209 } myStruct;1210 1211 typedef struct yourStruct { // OK1212 struct yourStruct *next;1213 int x;1214 } yourStruct;1215 \end{verbatim}1216 1172 1217 1173 %------------------------------------------------------------------------------
Note:
See TracChangeset
for help on using the changeset viewer.
