1 == Asterisk Patch/Coding Guidelines ==
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
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:
10 - the base code you are working from is in ~/work/asterisk-base
11 - the changes are in ~/work/asterisk-new
13 ~/work$ diff -urN asterisk-base asterisk-new
15 All code, filenames, function names and comments must be in ENGLISH.
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.
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
24 Don't make unnecessary whitespace changes throughout the code.
26 Don't use C++ type (//) comments.
28 Try to match the existing formatting of the file you are working on.
30 Functions and variables that are not intended to be global must be
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.
37 Roughly, Asterisk code formatting guidelines are generally equivalent to the
40 # indent -i4 -ts4 -br -brs -cdw -cli0 -ce -nbfda -npcs -npsl foo.c
42 Function calls and arguments should be spaced in a consistent way across
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);
50 Following are examples of how code should be formatted.
53 int foo(int a, char *s)
75 No nested statements without braces, e.g. no:
90 Don't build code like this:
93 /* .... 50 lines of code ... */
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'
108 .... 50 lines of code ....
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.
114 Make sure you never use an uninitialized variable. The compiler will
115 usually warn you if you do so.
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
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]
126 When making applications, always ast_strdupa(data) to a local pointer if
127 you intend to parse it.
130 mydata = ast_strdupa(data);
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);
137 If you do the same or a similar operation more than 1 time, make it a
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
145 When you achieve your desired functionalty, make another few refactor
146 passes over the code to optimize it.
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.
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.
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 &.
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.
165 Just an example, so don't over analyze it, that'd be a shame:
168 const char *prefix = "pre";
169 const char *postfix = "post";
170 char *newname = NULL;
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);
178 const char *prefix = "pre";
179 const char *postfix = "post";
180 char *newname = NULL;
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);
188 Use const on pointers which your function will not be modifying, as this
189 allows the compiler to make certain optimizations.
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).
196 When allocating/zeroing memory for a structure, try to use code like this:
202 tmp = malloc(sizeof(*tmp));
204 memset(tmp, 0, sizeof(*tmp));
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:
214 tmp = calloc(1, sizeof(*tmp));
216 This will allocate and zero the memory in a single operation.
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:
223 *CLI> iax2 show peer <peername>
227 *CLI> show iax2 peer <peername>
229 == New dialplan applications/functions ==
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).
240 Applications are registered and invoked using the
241 ast_register_application function; see the apps/app_skel.c file for an
244 Functions are registered using 'struct ast_custom_function'
245 structures and the ast_custom_function_register function.
247 == Doxygen API Documentation Guidelines ==
249 When writing Asterisk API documentation the following format should be
253 * \brief Do interesting stuff.
254 * \param thing1 interesting parameter 1.
255 * \param thing2 interesting parameter 2.
257 * This function does some interesting stuff.
259 * \return zero on success, -1 on error.
261 int ast_interesting_stuff(int thing1, int thing2)
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.
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.
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'.
279 Structures should be documented as follows.
282 * \brief A very interesting structure.
284 struct interesting_struct
286 /*! \brief A data member. */
289 int member2; /*!< \brief Another data member. */
292 Note that /*! */ blocks document the construct immediately following them
293 unless they are written, /*!< */, in which case they document the construct