b9fcfba1e2756462ce8b7b1cdf0292e654121048
[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.
8
9 All code, filenames, function names and comments must be in ENGLISH.
10
11 Do not declare variables mid-function (e.g. like GNU lets you) since it is
12 harder to read and not portable to GCC 2.95 and others.
13
14 Don't annotate your changes with comments like "/* JMG 4/20/04 */";
15 Comments should explain what the code does, not when something was changed
16 or who changed it.
17
18 Don't make unnecessary whitespace changes throughout the code.
19
20 Don't use C++ type (//) comments.
21
22 Try to match the existing formatting of the file you are working on.
23
24 Functions and variables that are not intended to be global must be
25 declared static.
26
27 When reading integer numeric input with scanf (or variants), do _NOT_ use '%i'
28 unless specifically want to allow non-base-10 input; '%d' is always a better
29 choice, since it will not silently turn numbers with leading zeros into base-8.
30
31 Roughly, Asterisk coding guidelines are generally equivalent to the 
32 following:
33
34 # indent -i4 -ts4 -br -brs -cdw -cli0 -ce -nbfda -npcs -npsl foo.c
35
36 Function calls and arguments should be spaced in a consistent way across
37 the codebase.
38 GOOD: foo(arg1, arg2);
39 GOOD: foo(arg1,arg2);   /* Acceptable but not preferred */
40 BAD: foo (arg1, arg2);
41 BAD: foo( arg1, arg2 );
42 BAD: foo(arg1, arg2,arg3);
43
44 Following are examples of how code should be formatted.
45
46 Functions:
47 int foo(int a, char *s)
48 {
49         return 0;
50 }
51
52 If statements:
53 if (foo) {
54         bar();
55 } else {
56         blah();
57 }
58
59 Case statements:
60 switch (foo) {
61 case BAR:
62         blah();
63         break;
64 case OTHER:
65         other();
66         break;
67 }
68
69 No nested statements without braces, e.g. no:
70
71 for (x=0;x<5;x++)
72         if (foo) 
73                 if (bar)
74                         baz();
75
76 instead do:
77 for (x=0;x<5;x++) {
78         if (foo) {
79                 if (bar)
80                         baz();
81         }
82 }
83
84
85 Make sure you never use an uninitialized variable.  The compiler will 
86 usually warn you if you do so.
87
88 Name global variables (or local variables when you have a lot of them or
89 are in a long function) something that will make sense to aliens who
90 find your code in 100 years.  All variable names should be in lower 
91 case.
92
93 Make some indication in the name of global variables which represent
94 options that they are in fact intended to be global.
95  e.g.: static char global_something[80]
96
97 When making applications, always ast_strdupa(data) to a local pointer if
98 you intend to parse it.
99  if(data)
100   mydata = ast_strdupa(data);
101
102 Always derefrence or localize pointers to things that are not yours like
103 channel members in a channel that is not associated with the current 
104 thread and for which you do not have a lock.
105  channame = ast_strdupa(otherchan->name);
106
107 If you do the same or a similar operation more than 1 time, make it a
108 function or macro.
109
110 Make sure you are not duplicating any functionality already found in an
111 API call somewhere.  If you are duplicating functionality found in 
112 another static function, consider the value of creating a new API call 
113 which can be shared.
114
115 When you achieve your desired functionalty, make another few refactor
116 passes over the code to optimize it.
117
118 Before submitting a patch, *read* the actual patch file to be sure that 
119 all the changes you expect to be there are, and that there are no 
120 surprising changes you did not expect.
121
122 If you are asked to make changes to your patch, there is a good chance
123 the changes will introduce bugs, check it even more at this stage.
124
125 Avoid needless malloc(),strdup() calls.  If you only need the value in
126 the scope of your function try ast_strdupa() or declare struts static
127 and pass them as a pointer with &.
128
129 If you are going to reuse a computable value, save it in a variable
130 instead of recomputing it over and over.  This can prevent you from 
131 making a mistake in subsequent computations, make it easier to correct
132 if the formula has an error and may or may not help optimization but 
133 will at least help readability.
134
135 Just an example, so don't over analyze it, that'd be a shame:
136
137
138 const char *prefix = "pre";     
139 const char *postfix = "post";
140 char *newname = NULL;
141 char *name = "data";
142
143 if (name && (newname = (char *) alloca(strlen(name) + strlen(prefix) + strlen(postfix) + 3)))
144         snprintf(newname, strlen(name) + strlen(prefix) + strlen(postfix) + 3, "%s/%s/%s", prefix, name, postfix);
145
146 vs
147
148 const char *prefix = "pre";
149 const char *postfix = "post";
150 char *newname = NULL;
151 char *name = "data";
152 int len = 0;
153
154 if (name && (len = strlen(name) + strlen(prefix) + strlen(postfix) + 3) && (newname = (char *) alloca(len)))
155         snprintf(newname, len, "%s/%s/%s", prefix, name, postfix);
156
157
158 Use const on pointers which your function will not be modifying, as this 
159 allows the compiler to make certain optimizations.
160
161 == CLI Commands ==
162
163 New CLI commands should be named using the module's name, followed by a verb
164 and then any parameters that the command needs. For example:
165
166 *CLI> iax2 show peer <peername>
167
168 not
169
170 *CLI> show iax2 peer <peername>