2f18daada4c9d01d25d6723181775e87c116b0b6
[dpkg/dpkg.git] / doc / coding-style.txt
1 Dpkg C coding style 2012-05-24
2 ===================
3
4 C language extensions
5 ~~~~~~~~~~~~~~~~~~~~~
6
7 The code base assumes C89 plus the following C99 extensions:
8
9  * Named initializers.
10  * Trailing comma in enum.
11  * Variadic macros.
12  * Working bool type in <stdbool.h>.
13  * Working %j and %z printf modifiers.
14  * Magic __func__ variable.
15
16 Those are checked at build time, and it will abort in case a needed extension
17 is not supported.
18
19 General
20 ~~~~~~~
21
22 The coding style is a mix of parts from KNF [K] and the Linux CodingStyle [L].
23 If in doubt or missing from this file please ask, although files using the
24 tab based indentation can be considered canon.
25
26   [K] <https://www.freebsd.org/cgi/man.cgi?query=style>
27   [L] <https://www.kernel.org/doc/Documentation/CodingStyle>
28
29 The code has a mix of an old coding style being phased out and the new
30 style. New files should use the new style, changes to files with the old
31 style should switch the code being touched except for the indentation level,
32 which should be preserved to match (2 spaces).
33
34 Code should generally strive for clarity. Monster functions should be split
35 into logical and small pieces.
36
37 Variable and function names should be generally descriptive, not needed
38 for variables commonly used (for example an index inside a loop, etc),
39 acronyms should only be used if they are widely known externally or
40 inside the project. The names should separate logical concepts within
41 with underscores.
42
43 On comments use UTF-8 characters for quotes, copyright symbols, etc.
44
45 On strings in code use simple or double quotes «''» «""». Not the unpaired
46 ones «`'». Strings marked for translation, should only be fixed if there's
47 other changes to be done on them, otherwise we get unneeded fuzzies.
48
49   <https://www.cl.cam.ac.uk/~mgk25/ucs/quotes.html>
50
51 Code documentation
52 ~~~~~~~~~~~~~~~~~~
53
54 Public declarations should be documented using JavaDoc style comments.
55
56 Documentation should always be close to its definition (usually in the .c
57 or .cc files) and not its declaration, so that when the code changes it's
58 less likely that they will get out of sync. For data types, macros and
59 similar where there's only declarations, the documentation will usually
60 go instead in the header files.
61
62 For enum values and struct members, the documentation should usually be
63 one-line comments, preceding the item.
64
65 The comment title should be on the second line on its own, and the long
66 description on its own paragraph.
67
68 Examples:
69
70 /**
71  * This is the enum title.
72  */
73 enum value_list {
74         /** Value doing foo. */
75         value_a,
76         /** Value doing bar. */
77         value_b,
78 };
79
80 /**
81  * This is the title.
82  *
83  * This is the long description extending several lines, explaining in
84  * detail what this item does.
85  *
86  * @param a This is the a parameter.
87  * @param b This is the b parameter.
88  *
89  * @return This is the return value.
90  */
91
92 Indentation, alignment and spacing
93 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
94
95 Lines should be 80 chars max. Indentation is done with hard tabs (which
96 should be considered to take 8 spaces width). Aligning with spaces:
97
98 static void
99 function(void *ptr, int value)
100 {
101         void *ref_ptr = get_ref(ptr);
102         int ref_value = get_value(ref);
103
104         if (value > 10)
105                 do_something(GLOBAL_MACRO, ptr, value, "some-string",
106                              ref_ptr, ref_value, "other-string",
107                              "extra-string");
108 }
109
110 When wrapping, logical operators should be kept on the preceding line:
111
112         if (really_long_variable_to_be_checked_against_a &&
113             really_long_variable_to_be_checked_against_b)
114                 foo();
115
116 Spaces between operators:
117
118         if (a && (b || c) && c == d)
119                 break;
120
121         a = (b + 4 * (5 - 6)) & 0xff;
122
123 Spaces between assignments:
124
125         a += b;
126
127 Spaces after comma:
128
129         foo(a, b);
130
131 Space after keywords (for, while, do, if, etc, but sizeof should be
132 treated like a function):
133
134         for (i = 0; i < 10; i++)
135                 foo(i);
136
137         memcpy(dst, src, sizeof(src));
138
139 Definition of local variables, related code blocks, functions bodies
140 should be split with blank lines:
141
142 int
143 function(void)
144 {
145         int a;
146
147         foo();
148         bar();
149
150         quux();
151
152         return 0;
153 }
154
155 Braces
156 ~~~~~~
157
158 Braces should be placed on the same line as the keyword, but on a new line
159 for the function body. No braces should be used for unambiguous one line
160 statements:
161
162         if (a > 0) {
163                 foo(a);
164                 bar(a);
165         } else {
166                 quux(0)
167                 bar(0);
168         }
169
170         for (;;) {
171                 foo();
172                 bar();
173         }
174
175         do {
176                 foo();
177                 bar();
178         } while (quux());
179
180         switch (foo) {
181         case a:
182                 bar();
183                 break;
184         case b:
185         default:
186                 baz();
187                 break;
188         }
189
190 Code conventions
191 ~~~~~~~~~~~~~~~~
192
193 Prefer assigning outside of conditionals:
194
195         n = read_items();
196         if (n < 100)
197                 foo();
198
199 String comparisons should use comparison operators to make it easier to
200 see what operation is being done:
201
202         if (strcmp(a, b) == 0)
203                 foo();
204
205         if (strcmp(a, b) < 0)
206                 foo();
207
208
209 Dpkg Perl coding style 2013-01-04
210 ======================
211
212 General
213 ~~~~~~~
214
215 In general you should follow the conventions listed in perlstyle(1).
216 All the code should run with the “use strict” and “use warnings” pragmas.
217
218 Code documentation
219 ~~~~~~~~~~~~~~~~~~
220
221 Public modules should be documented with POD (see perlpod(1)). Private
222 code doesn't have to use POD, simple comment lines (starting with "#") are
223 enough. Public scripts are documented in their corresponding manual pages.
224
225 Indentation, alignment and spacing
226 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
227
228 Lines should be 80 chars max. The indentation level is 4 characters, and
229 indentation is done with hard tabs (which should be considered to take 8
230 spaces width) and spaces.
231
232 if ($foo) {
233     if ($bar) {
234         print "Hello\n";
235         unless ($baz) {
236             print "Who are you?\n";
237         }
238     }
239 }
240
241 Perl version
242 ~~~~~~~~~~~~
243
244 We don't want to impose a too-recent Perl version, so only use features
245 supported by the Perl version that is currently in Debian oldstable when
246 possible. Currently that means Perl 5.10.0.
247
248 Object methods
249 ~~~~~~~~~~~~~~
250
251 Use a single line to retrieve all the arguments and use $self as name
252 for the current object:
253
254 sub do_something {
255     my ($self, $arg1, $arg2, %opts) = @_;
256     ...
257 }
258
259 Supplementary optional arguments should be named and thus stored in a
260 hash.