doc/Programming-Guide/02_CodingConventions.dox

   1 /**
   2 \page Conventions Coding and Other Conventions used in Squid
   3
   4 \section Coding Code Conventions
   5 \par
   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.
   8
   9 \section FWT Fixed Width types
  10
  11 \par
  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".
  15
  16 \verbatim
  17         int16_t    -  16 bit signed.
  18         uint16_t  -  16 bit unsigned.
  19         int32_t    -  32 bit signed.
  20         uint32_t  -  32 bit unsigned.
  21         int64_t    -  64 bit signed.
  22         uint64_t  -  64 bit unsigned.
  23 \endverbatim
  24
  25 \section Documentation Documentation Conventions
  26 \par
  27         Now that documentation is generated automatically from the sources
  28         some common comment conventions need to be adopted.
  29
  30
  31 \subsection CommentComponents   API vs Internal Component Commenting
  32
  33 \par
  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.
  40
  41 \par
  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).
  46
  47 \par
  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.
  53
  54 \par    Rule of thumb:
  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.
  58
  59 \subsection FunctionComments    Function/Method Comments
  60
  61 \par
  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.
  64
  65 \par
  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
  68         there.
  69
  70
  71 \subsubsection PARAM    Function Parameters
  72
  73 \par
  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.
  78
  79 \par
  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.
  83
  84 \par
  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.
  89
  90 \par    For Example:
  91 \verbatim
  92 /**
  93  \param g[out]          Buffer to receive something
  94  \param glen[in]        Length of buffer available to write
  95  */
  96 void
  97 X::getFubar(char *g, int glen)
  98 ...
  99 \endverbatim
 100
 101
 102 \subsubsection RETVAL   Return Values
 103
 104 \par
 105         Each function that returns a value should have the possible range of values
 106         commented in the pre-function descriptor.
 107 \par
 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.
 111
 112 \par    For Example:
 113 \verbatim
 114 /**
 115  \retval 0      when FUBAR does not start with 'F'
 116  \retval 1      when FUBAR startes with F
 117  */
 118 int
 119 X::saidFubar()
 120 ...
 121 \endverbatim
 122
 123 \par    Alternatively
 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
 126         content.
 127
 128
 129 \subsubsection FLOW     Function Actions / Internal Flows
 130
 131 \par    Simple functions
 132         do not exactly need a detailed description of their operation.
 133         The \ref PARAM and \ref RETVAL
 134         should be enough for any developer to understand the function.
 135
 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
 142         \arg etc, etc.
 143
 144 \par
 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.
 150
 151 \par    For example:
 152 \verbatim
 153 /**
 154  \param g       The buffer to be used
 155  \param glen    Length of buffer provided
 156  \param state   Object of type X storing foo
 157  */
 158 void
 159 fubar(char *g, int glen, void *state) {
 160 \endverbatim
 161         Designed validation part of the function
 162 \verbatim
 163     /** \par
 164      * When g is NULL or gen is 0 nothing is done */
 165     if(g == NULL || glen < 1)
 166         return;
 167
 168    /** \par
 169      * When glen is longer than the accepted length it gets truncated */
 170    if(glen > MAX_FOO) glen = MAX_FOO;
 171 \endverbatim
 172         now we get on to the active part of the function
 173 \verbatim
 174    /** \par
 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.
 178      */
 179    memcpy(g, glen, state->foo_end_ptr );
 180    state->foo_end_ptr += glen;
 181    fubar(state);
 182 }
 183 \endverbatim
 184
 185 \par
 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.
 190
 191  */