add a minor allocation/zeroing guideline
[asterisk/asterisk.git] / 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  if(data)
129   mydata = ast_strdupa(data);
130
131 Always derefrence or localize pointers to things that are not yours like
132 channel members in a channel that is not associated with the current 
133 thread and for which you do not have a lock.
134  channame = ast_strdupa(otherchan->name);
135
136 If you do the same or a similar operation more than 1 time, make it a
137 function or macro.
138
139 Make sure you are not duplicating any functionality already found in an
140 API call somewhere.  If you are duplicating functionality found in 
141 another static function, consider the value of creating a new API call 
142 which can be shared.
143
144 When you achieve your desired functionalty, make another few refactor
145 passes over the code to optimize it.
146
147 Before submitting a patch, *read* the actual patch file to be sure that 
148 all the changes you expect to be there are, and that there are no 
149 surprising changes you did not expect.
150
151 If you are asked to make changes to your patch, there is a good chance
152 the changes will introduce bugs, check it even more at this stage.
153
154 Avoid needless malloc(),strdup() calls.  If you only need the value in
155 the scope of your function try ast_strdupa() or declare struts static
156 and pass them as a pointer with &.
157
158 If you are going to reuse a computable value, save it in a variable
159 instead of recomputing it over and over.  This can prevent you from 
160 making a mistake in subsequent computations, make it easier to correct
161 if the formula has an error and may or may not help optimization but 
162 will at least help readability.
163
164 Just an example, so don't over analyze it, that'd be a shame:
165
166
167 const char *prefix = "pre";     
168 const char *postfix = "post";
169 char *newname = NULL;
170 char *name = "data";
171
172 if (name && (newname = (char *) alloca(strlen(name) + strlen(prefix) + strlen(postfix) + 3)))
173         snprintf(newname, strlen(name) + strlen(prefix) + strlen(postfix) + 3, "%s/%s/%s", prefix, name, postfix);
174
175 vs
176
177 const char *prefix = "pre";
178 const char *postfix = "post";
179 char *newname = NULL;
180 char *name = "data";
181 int len = 0;
182
183 if (name && (len = strlen(name) + strlen(prefix) + strlen(postfix) + 3) && (newname = (char *) alloca(len)))
184         snprintf(newname, len, "%s/%s/%s", prefix, name, postfix);
185
186
187 Use const on pointers which your function will not be modifying, as this 
188 allows the compiler to make certain optimizations.
189
190 Don't use strncpy for copying whole strings; it does not guarantee that the
191 output buffer will be null-terminated. Use ast_copy_string instead, which
192 is also slightly more efficient (and allows passing the actual buffer
193 size, which makes the code clearer).
194
195 When allocating/zeroing memory for a structure, try to use code like this:
196
197 struct foo *tmp;
198
199 ...
200
201 tmp = malloc(sizeof(*tmp));
202 if (tmp)
203   memset(tmp, 0, sizeof(*tmp));
204
205 This eliminates duplication of the 'struct foo' identifier, which makes the
206 code easier to read and also ensures that if it is copy-and-pasted it won't
207 require as much editing. In fact, you can even use:
208
209 struct foo *tmp;
210
211 ...
212
213 tmp = calloc(1, sizeof(*tmp));
214
215 This will allocate and zero the memory in a single operation.
216
217 == CLI Commands ==
218
219 New CLI commands should be named using the module's name, followed by a verb
220 and then any parameters that the command needs. For example:
221
222 *CLI> iax2 show peer <peername>
223
224 not
225
226 *CLI> show iax2 peer <peername>
227
228 == New dialplan applications/functions ==
229
230 There are two methods of adding functionality to the Asterisk
231 dialplan: applications and functions. Applications (found generally in
232 the apps/ directory) should be collections of code that interact with
233 a channel and/or user in some significant way. Functions (which can be
234 provided by any type of module) are used when the provided
235 functionality is simple... getting/retrieving a value, for
236 example. Functions should also be used when the operation is in no way
237 related to a channel (a computation or string operation, for example).
238
239 Applications are registered and invoked using the
240 ast_register_application function; see the apps/app_skel.c file for an
241 example.
242
243 Functions are registered using 'struct ast_custom_function'
244 structures and the ast_custom_function_register function.