2 \page Conventions Coding and Other Conventions used in Squid
4 \section Coding Code Conventions
6 Most custom types and tools are documented in the code or the relevant
7 portions of this manual. Some key points apply globally however.
9 \section FWT Fixed Width types
12 If you need to use specific width types - such as
13 a 16 bit unsigned integer, use one of the following types. To access
14 them simply include "config.h".
17 int16_t - 16 bit signed.
18 u_int16_t - 16 bit unsigned.
19 int32_t - 32 bit signed.
20 u_int32_t - 32 bit unsigned.
21 int64_t - 64 bit signed.
22 u_int64_t - 64 bit unsigned.
25 \section Documentation Documentation Conventions
27 Now that documentation is generated automatically from the sources
28 some common comment conventions need to be adopted.
31 \subsection CommentComponents API vs Internal Component Commenting
34 First among these is a definition seperation between component API
35 and Internal operations. API functions and objects should always be
36 commented and in the *.h file for the component. Internal logics and
37 objects should be commented in the *.cc file where they are defined.
38 The group is to be defined in the components main files with the
39 overview paragraphs about the API usage or component structure.
42 With C++ classes it is easy to seperate API and Internals with the C++
43 public: and private: distinctions on whichever class defines the
44 component API. An Internal group may not be required if there are no
45 additional items in the Internals (rare as globals are common in squid).
48 With unconverted modules still coded in Objective-C, the task is harder.
49 In these cases two sub-groups must be defined *API and *Internal into
50 which naturally individual functions, variables, etc. are grouped using
51 the \b \\ingroup tag. The API group is usually a sub-group of Components
52 and the Internal is always a sub-group of the API.
55 For both items, if its referenced from elsewhere in the code or
56 defined in the .h file it should be part of the API.
57 Everything else should be in the Internals group and kept out of the .h file.
59 \subsection FunctionComments Function/Method Comments
62 All descriptions may be more than one line, and while whitespace formatting is
63 ignored by doxygen, it is good to keep it clear for manual reading of the code.
66 Any text directly following a \b \\par tag will be highlighted in bold
67 automatically (like all the 'For Examples' below) so be careful what is placed
71 \subsubsection PARAM Function Parameters
74 Function and Method parameters MUST be named in both the definition and in
75 the declaration, and they also MUST be the same text. The doxygen parser
76 needs them to be identical to accurately link the two with documentation.
77 Particularly linking function with documentation of the label itself.
80 Each function that takes parameters should have the possible range of values
81 commented in the pre-function descriptor. For API function this is as usual
82 in the .h file, for Internal functions it is i the .(cc|cci) file.
85 The \b \\param tag is used to describe these. It takes two required parameters;
86 the name of the function parameter being documented followed immediately by
87 either [in], [out], or [in,out].
88 Followed by an optional description of what the parameter represents.
93 \param g[out] Buffer to receive something
94 \param glen[in] Length of buffer available to write
97 X::getFubar(char *g, int glen)
102 \subsubsection RETVAL Return Values
105 Each function that returns a value should have the possible range of values
106 commented in the pre-function descriptor.
108 The \b \\retval tag is used to describe these. It takes one required parameter;
109 the value or range of values returned.
110 Followed by an optional description of what/why of that value.
115 \retval 0 when FUBAR does not start with 'F'
116 \retval 1 when FUBAR startes with F
124 when a state or other context-dependant object is returned the \b \return
125 tag is used. It is followed by a description of the object and ideally its
129 \subsubsection FLOW Function Actions / Internal Flows
131 \par Simple functions
132 do not exactly need a detailed description of their operation.
133 The \link PARAM input parameters \endlink and \link RETVAL Return \endlink
134 value should be enough for any developer to understand the function.
136 \par Long or Complex Functions
137 do however need some commenting.
138 A well-designed function does all its operatons in distinct blocks;
139 \arg Input validation
140 \arg Processing on some state
141 \arg Processing on the output of that earlier processing
145 Each of these design blocks inside the function should be given a comment
146 indicating what they do. The comments should begin with
147 \verbatim /** \par \endverbatim
148 The resulting function description will then contain a paragraph on each of the
149 blocks in the order they occur in the function.
154 \param g The buffer to be used
155 \param glen Length of buffer provided
156 \param state Object of type X storing foo
159 fubar(char *g, int glen, void *state) {
161 Designed validation part of the function
164 * When g is NULL or gen is 0 nothing is done */
165 if(g == NULL || glen < 1)
169 * When glen is longer than the accepted length it gets truncated */
170 if(glen > MAX_FOO) glen = MAX_FOO;
172 now we get on to the active part of the function
175 * Appends up to MAX_FOO bytes from g onto the end of state->foo
176 * then passes the state off to FUBAR.
177 * No check for null-termination is done.
179 xmemcpy(g, glen, state->foo_end_ptr );
180 state->foo_end_ptr += glen;
186 Of course, this is a very simple example. This type of comment should only be
187 needed in the larger functions with many side effects.
188 A function this small could reasonably have all its commenting done just ahead of
189 the parameter description.