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