doc/CODING-GUIDELINES

   1 == Asterisk Patch/Coding Guidelines ==
   2
   3 To be accepted into the codebase, all non-trivial changes must be
   4 disclaimed to Digium or placed in the public domain. For more information
   5 see http://bugs.digium.com
   6
   7 Patches should be in the form of a unified (-u) diff, made from the directory
   8 above the top-level Asterisk source directory. For example:
   9
  10 - the base code you are working from is in ~/work/asterisk-base
  11 - the changes are in ~/work/asterisk-new
  12
  13 ~/work$ diff -urN asterisk-base asterisk-new
  14
  15 All code, filenames, function names and comments must be in ENGLISH.
  16
  17 Do not declare variables mid-function (e.g. like GNU lets you) since it is
  18 harder to read and not portable to GCC 2.95 and others.
  19
  20 Don't annotate your changes with comments like "/* JMG 4/20/04 */";
  21 Comments should explain what the code does, not when something was changed
  22 or who changed it.
  23
  24 Don't make unnecessary whitespace changes throughout the code.
  25
  26 Don't use C++ type (//) comments.
  27
  28 Try to match the existing formatting of the file you are working on.
  29
  30 Functions and variables that are not intended to be global must be
  31 declared static.
  32
  33 When reading integer numeric input with scanf (or variants), do _NOT_ use '%i'
  34 unless specifically want to allow non-base-10 input; '%d' is always a better
  35 choice, since it will not silently turn numbers with leading zeros into base-8.
  36
  37 Roughly, Asterisk code formatting guidelines are generally equivalent to the
  38 following:
  39
  40 # indent -i4 -ts4 -br -brs -cdw -cli0 -ce -nbfda -npcs -npsl foo.c
  41
  42 Function calls and arguments should be spaced in a consistent way across
  43 the codebase.
  44 GOOD: foo(arg1, arg2);
  45 GOOD: foo(arg1,arg2);   /* Acceptable but not preferred */
  46 BAD: foo (arg1, arg2);
  47 BAD: foo( arg1, arg2 );
  48 BAD: foo(arg1, arg2,arg3);
  49
  50 Following are examples of how code should be formatted.
  51
  52 Functions:
  53 int foo(int a, char *s)
  54 {
  55         return 0;
  56 }
  57
  58 If statements:
  59 if (foo) {
  60         bar();
  61 } else {
  62         blah();
  63 }
  64
  65 Case statements:
  66 switch (foo) {
  67 case BAR:
  68         blah();
  69         break;
  70 case OTHER:
  71         other();
  72         break;
  73 }
  74
  75 No nested statements without braces, e.g. no:
  76
  77 for (x=0;x<5;x++)
  78         if (foo)
  79                 if (bar)
  80                         baz();
  81
  82 instead do:
  83 for (x=0;x<5;x++) {
  84         if (foo) {
  85                 if (bar)
  86                         baz();
  87         }
  88 }
  89
  90 Don't build code like this:
  91
  92 if (foo) {
  93         /* .... 50 lines of code ... */
  94 } else {
  95         result = 0;
  96         return;
  97 }
  98
  99 Instead, try to minimize the number of lines of code that need to be
 100 indented, by only indenting the shortest case of the 'if'
 101 statement, like so:
 102
 103 if !(foo) {
 104         result = 0;
 105         return;
 106 }
 107
 108 .... 50 lines of code ....
 109
 110 When this technique is used properly, it makes functions much easier to read
 111 and follow, especially those with more than one or two 'setup' operations
 112 that must succeed for the rest of the function to be able to execute.
 113
 114 Make sure you never use an uninitialized variable.  The compiler will
 115 usually warn you if you do so.
 116
 117 Name global variables (or local variables when you have a lot of them or
 118 are in a long function) something that will make sense to aliens who
 119 find your code in 100 years.  All variable names should be in lower
 120 case.
 121
 122 Make some indication in the name of global variables which represent
 123 options that they are in fact intended to be global.
 124  e.g.: static char global_something[80]
 125
 126 When making applications, always ast_strdupa(data) to a local pointer if
 127 you intend to parse it.
 128
 129         if (data)
 130                 mydata = ast_strdupa(data);
 131
 132 Always derefrence or localize pointers to things that are not yours like
 133 channel members in a channel that is not associated with the current
 134 thread and for which you do not have a lock.
 135         channame = ast_strdupa(otherchan->name);
 136
 137 If you do the same or a similar operation more than 1 time, make it a
 138 function or macro.
 139
 140 Make sure you are not duplicating any functionality already found in an
 141 API call somewhere.  If you are duplicating functionality found in
 142 another static function, consider the value of creating a new API call
 143 which can be shared.
 144
 145 When you achieve your desired functionalty, make another few refactor
 146 passes over the code to optimize it.
 147
 148 Before submitting a patch, *read* the actual patch file to be sure that
 149 all the changes you expect to be there are, and that there are no
 150 surprising changes you did not expect.
 151
 152 If you are asked to make changes to your patch, there is a good chance
 153 the changes will introduce bugs, check it even more at this stage.
 154
 155 Avoid needless malloc(),strdup() calls.  If you only need the value in
 156 the scope of your function try ast_strdupa() or declare struts static
 157 and pass them as a pointer with &.
 158
 159 If you are going to reuse a computable value, save it in a variable
 160 instead of recomputing it over and over.  This can prevent you from
 161 making a mistake in subsequent computations, make it easier to correct
 162 if the formula has an error and may or may not help optimization but
 163 will at least help readability.
 164
 165 Just an example, so don't over analyze it, that'd be a shame:
 166
 167
 168 const char *prefix = "pre";
 169 const char *postfix = "post";
 170 char *newname = NULL;
 171 char *name = "data";
 172
 173 if (name && (newname = (char *) alloca(strlen(name) + strlen(prefix) + strlen(postfix) + 3)))
 174         snprintf(newname, strlen(name) + strlen(prefix) + strlen(postfix) + 3, "%s/%s/%s", prefix, name, postfix);
 175
 176 vs
 177
 178 const char *prefix = "pre";
 179 const char *postfix = "post";
 180 char *newname = NULL;
 181 char *name = "data";
 182 int len = 0;
 183
 184 if (name && (len = strlen(name) + strlen(prefix) + strlen(postfix) + 3) && (newname = (char *) alloca(len)))
 185         snprintf(newname, len, "%s/%s/%s", prefix, name, postfix);
 186
 187
 188 Use const on pointers which your function will not be modifying, as this
 189 allows the compiler to make certain optimizations.
 190
 191 Don't use strncpy for copying whole strings; it does not guarantee that the
 192 output buffer will be null-terminated. Use ast_copy_string instead, which
 193 is also slightly more efficient (and allows passing the actual buffer
 194 size, which makes the code clearer).
 195
 196 When allocating/zeroing memory for a structure, try to use code like this:
 197
 198 struct foo *tmp;
 199
 200 ...
 201
 202 tmp = malloc(sizeof(*tmp));
 203 if (tmp)
 204         memset(tmp, 0, sizeof(*tmp));
 205
 206 This eliminates duplication of the 'struct foo' identifier, which makes the
 207 code easier to read and also ensures that if it is copy-and-pasted it won't
 208 require as much editing. In fact, you can even use:
 209
 210 struct foo *tmp;
 211
 212 ...
 213
 214 tmp = calloc(1, sizeof(*tmp));
 215
 216 This will allocate and zero the memory in a single operation.
 217
 218 == CLI Commands ==
 219
 220 New CLI commands should be named using the module's name, followed by a verb
 221 and then any parameters that the command needs. For example:
 222
 223 *CLI> iax2 show peer <peername>
 224
 225 not
 226
 227 *CLI> show iax2 peer <peername>
 228
 229 == New dialplan applications/functions ==
 230
 231 There are two methods of adding functionality to the Asterisk
 232 dialplan: applications and functions. Applications (found generally in
 233 the apps/ directory) should be collections of code that interact with
 234 a channel and/or user in some significant way. Functions (which can be
 235 provided by any type of module) are used when the provided
 236 functionality is simple... getting/retrieving a value, for
 237 example. Functions should also be used when the operation is in no way
 238 related to a channel (a computation or string operation, for example).
 239
 240 Applications are registered and invoked using the
 241 ast_register_application function; see the apps/app_skel.c file for an
 242 example.
 243
 244 Functions are registered using 'struct ast_custom_function'
 245 structures and the ast_custom_function_register function.
 246
 247 == Doxygen API Documentation Guidelines ==
 248
 249 When writing Asterisk API documentation the following format should be
 250 followed.
 251
 252 /*!
 253  * \brief Do interesting stuff.
 254  * \param thing1 interesting parameter 1.
 255  * \param thing2 interesting parameter 2.
 256  *
 257  * This function does some interesting stuff.
 258  *
 259  * \return zero on success, -1 on error.
 260  */
 261 int ast_interesting_stuff(int thing1, int thing2)
 262 {
 263         return 0;
 264 }
 265
 266 Notice the use of the \param, \brief, and \return constructs.  These should be
 267 used to describe the corresponding pieces of the function being documented.
 268 Also notice the blank line after the last \param directive.  All doxygen
 269 comments must be in one /*! */ block.  If the function or struct does not need
 270 an extended description it can be left out.
 271
 272 Please make sure to review the doxygen manual and make liberal use of the \a,
 273 \code, \c, \b, \note, \li and \e modifiers as appropriate.
 274
 275 When documenting a 'static' function or an internal structure in a module,
 276 use the \internal modifier to ensure that the resulting documentation
 277 explicitly says 'for internal use only'.
 278
 279 Structures should be documented as follows.
 280
 281 /*!
 282  * \brief A very interesting structure.
 283  */
 284 struct interesting_struct
 285 {
 286         /*! \brief A data member. */
 287         int member1;
 288
 289         int member2; /*!< \brief Another data member. */
 290 }
 291
 292 Note that /*! */ blocks document the construct immediately following them
 293 unless they are written, /*!< */, in which case they document the construct
 294 preceding them.