more strncpy -> ast_copy_string conversions, fixing some buglets along the way
[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 coding 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
91 Make sure you never use an uninitialized variable.  The compiler will 
92 usually warn you if you do so.
93
94 Name global variables (or local variables when you have a lot of them or
95 are in a long function) something that will make sense to aliens who
96 find your code in 100 years.  All variable names should be in lower 
97 case.
98
99 Make some indication in the name of global variables which represent
100 options that they are in fact intended to be global.
101  e.g.: static char global_something[80]
102
103 When making applications, always ast_strdupa(data) to a local pointer if
104 you intend to parse it.
105  if(data)
106   mydata = ast_strdupa(data);
107
108 Always derefrence or localize pointers to things that are not yours like
109 channel members in a channel that is not associated with the current 
110 thread and for which you do not have a lock.
111  channame = ast_strdupa(otherchan->name);
112
113 If you do the same or a similar operation more than 1 time, make it a
114 function or macro.
115
116 Make sure you are not duplicating any functionality already found in an
117 API call somewhere.  If you are duplicating functionality found in 
118 another static function, consider the value of creating a new API call 
119 which can be shared.
120
121 When you achieve your desired functionalty, make another few refactor
122 passes over the code to optimize it.
123
124 Before submitting a patch, *read* the actual patch file to be sure that 
125 all the changes you expect to be there are, and that there are no 
126 surprising changes you did not expect.
127
128 If you are asked to make changes to your patch, there is a good chance
129 the changes will introduce bugs, check it even more at this stage.
130
131 Avoid needless malloc(),strdup() calls.  If you only need the value in
132 the scope of your function try ast_strdupa() or declare struts static
133 and pass them as a pointer with &.
134
135 If you are going to reuse a computable value, save it in a variable
136 instead of recomputing it over and over.  This can prevent you from 
137 making a mistake in subsequent computations, make it easier to correct
138 if the formula has an error and may or may not help optimization but 
139 will at least help readability.
140
141 Just an example, so don't over analyze it, that'd be a shame:
142
143
144 const char *prefix = "pre";     
145 const char *postfix = "post";
146 char *newname = NULL;
147 char *name = "data";
148
149 if (name && (newname = (char *) alloca(strlen(name) + strlen(prefix) + strlen(postfix) + 3)))
150         snprintf(newname, strlen(name) + strlen(prefix) + strlen(postfix) + 3, "%s/%s/%s", prefix, name, postfix);
151
152 vs
153
154 const char *prefix = "pre";
155 const char *postfix = "post";
156 char *newname = NULL;
157 char *name = "data";
158 int len = 0;
159
160 if (name && (len = strlen(name) + strlen(prefix) + strlen(postfix) + 3) && (newname = (char *) alloca(len)))
161         snprintf(newname, len, "%s/%s/%s", prefix, name, postfix);
162
163
164 Use const on pointers which your function will not be modifying, as this 
165 allows the compiler to make certain optimizations.
166
167 Don't use strncpy for copying whole strings; it does not guarantee that the
168 output buffer will be null-terminated. Use ast_copy_string instead, which
169 is also slightly more efficient (and allows passing the actual buffer
170 size, which makes the code clearer).
171
172 == CLI Commands ==
173
174 New CLI commands should be named using the module's name, followed by a verb
175 and then any parameters that the command needs. For example:
176
177 *CLI> iax2 show peer <peername>
178
179 not
180
181 *CLI> show iax2 peer <peername>
182
183 == New dialplan applications/functions ==
184
185 There are two methods of adding functionality to the Asterisk
186 dialplan: applications and functions. Applications (found generally in
187 the apps/ directory) should be collections of code that interact with
188 a channel and/or user in some significant way. Functions (which can be
189 provided by any type of module) are used when the provided
190 functionality is simple... getting/retrieving a value, for
191 example. Functions should also be used when the operation is in no way
192 related to a channel (a computation or string operation, for example).
193
194 Applications are registered and invoked using the
195 ast_register_application function; see the apps/app_skel.c file for an
196 example.
197
198 Functions are registered using 'struct ast_custom_function'
199 structures and the ast_custom_function_register function.