Provide "ident" command line (at least the start of one)
[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 Roughly, Asterisk coding guidelines are generally equivalent to the 
28 following:
29
30 # indent -i4 -ts4 -br -brs -cdw -cli0 -ce -nbfda -npcs -npsl foo.c
31
32 Function calls and arguments should be spaced in a consistent way across
33 the codebase.
34 GOOD: foo(arg1, arg2);
35 GOOD: foo(arg1,arg2);   /* Acceptable but not preferred */
36 BAD: foo (arg1, arg2);
37 BAD: foo( arg1, arg2 );
38 BAD: foo(arg1, arg2,arg3);
39
40 Following are examples of how code should be formatted.
41
42 Functions:
43 int foo(int a, char *s)
44 {
45         return 0;
46 }
47
48 If statements:
49 if (foo) {
50         bar();
51 } else {
52         blah();
53 }
54
55 Case statements:
56 switch (foo) {
57 case BAR:
58         blah();
59         break;
60 case OTHER:
61         other();
62         break;
63 }
64
65 No nested statements without braces, e.g. no:
66
67 for (x=0;x<5;x++)
68         if (foo) 
69                 if (bar)
70                         baz();
71
72 instead do:
73 for (x=0;x<5;x++) {
74         if (foo) {
75                 if (bar)
76                         baz();
77         }
78 }