dpkg (1.18.25) stretch; urgency=medium
[dpkg] / doc / coding-style.txt
CommitLineData
1479465f
GJ
1Dpkg troff coding style 2016-01-29
2=======================
3
4General
5~~~~~~~
6
7Dashes that are relevant when copy & pasted need to be escaped (e.g. those
8present in program, file, argument and field names).
9
10New sentences inside a paragraph should start on a new line, so that we
11do not need to reflow the text when adding new content.
12
13Every new feature, option or behavior change needs to be documented with
14the version introducing the change.
15
16
17Dpkg M4sh/Autoconf coding style 1016-09-05
18===============================
19
20General
21~~~~~~~
22
23All dpkg specific macros need to be prefixed with «DPKG_». Complex checks
24should be defined as new macros under m4/dpkg-<name>.m4, and those used
25in configure.ac which should look pretty simple.
26
27Quoting and indentation
28~~~~~~~~~~~~~~~~~~~~~~~
29
30Code and arguments that wrap into the next line are indented by two spaces.
31
32In principle all macro argument should always be quoted. Which gives brings
33one of the biggest readability issues with M4sh/Autoconf code, the amount of
34consecutive quotes and parenthesis pairs, which can make it very hard to
35notice if they are unbalanced. To avoid this we use a style that tries to
36avoid more than two consecutive blocks of «])».
37
38We can either use a style resembling very simple function calls, when the
39arguments are as well very simple, such as:
40
41 AC_DEFINE_UNQUOTED([SOME_VARIABLE],
42 [SOME_CONCOCTED_WAY_TO_GET_A_VALUE],
43 [Some descriptive text here])
44
45 AS_CASE([condition],
46 [case-a], [do-a],
47 [case-b], [do-b])
48
49Or one resembling curly-braced C-style blocks, such as this:
50
51 AS_IF([condition], [
52 DO_SOMETHING([here])
53 ], [
54 DO_OTHERWISE([there])
55 ])
56
57Except for AC_ARG_WITH, AC_ARG_ENABLE and AM_CONDITIONAL which need their
58second argument quoted tightly surrounding the code, like this:
59
60 AC_ARG_ENABLE([feature],
61 [AS_HELP_STRING([--disable-feature], [Disable feature])],
62 [], [enable_feature="yes"])
63
64 AM_CONDITIONAL([HAVE_SOME_FEATURE],
65 [test "x$ac_cv_have_some_feature" = "xyes" && \
66 test "x$ac_cv_have_some_feature" = "xyes"])
67
68or the output will get messed up.
69
70
71Dpkg C/C++ coding style 2016-01-29
72=======================
73
74C language extensions
75~~~~~~~~~~~~~~~~~~~~~
76
77The code base assumes C89 plus the following C99 extensions:
78
79 * Designated initializers.
80 * Compound literals.
81 * Trailing comma in enum.
82 * Variadic macros.
83 * Working bool type in <stdbool.h>.
84 * Working %j and %z printf modifiers.
85 * Magic __func__ variable.
86
87Those are checked at build time, and it will abort in case a needed extension
88is not supported.
89
90C++ language extensions
91~~~~~~~~~~~~~~~~~~~~~~~
92
93The code base assumes C++03 plus the following C++11 extension:
94
95 * Null pointer keyword (nullptr).
96
97This is checked at build time, and it will use compatibility code in case the
98needed extension is not supported.
99
100General
101~~~~~~~
102
103The coding style is a mix of parts from KNF [K] and the Linux CodingStyle [L].
104If in doubt or missing from this file please ask, although files using the
105tab based indentation can be considered canon.
106
107 [K] <https://www.freebsd.org/cgi/man.cgi?query=style>
108 [L] <https://www.kernel.org/doc/Documentation/CodingStyle>
109
110The code has a mix of an old coding style being phased out and the new
111style. New files should use the new style, changes to files with the old
112style should switch the code being touched except for the indentation level,
113which should be preserved to match (2 spaces).
114
115Code should generally strive for clarity. Monster functions should be split
116into logical and small pieces.
117
118Variable and function names should be generally descriptive, not needed
119for variables commonly used (for example an index inside a loop, etc),
120acronyms should only be used if they are widely known externally or
121inside the project. The names should separate logical concepts within
122with underscores.
123
124On comments use UTF-8 characters for quotes, copyright symbols, etc.
125
126On strings in code use simple or double quotes «''» «""». Not the unpaired
127ones «`'». Strings marked for translation, should only be fixed if there's
128other changes to be done on them, otherwise we get unneeded fuzzies.
129
130 <https://www.cl.cam.ac.uk/~mgk25/ucs/quotes.html>
131
132Code documentation
133~~~~~~~~~~~~~~~~~~
134
135Public declarations should be documented using JavaDoc style comments.
136
137Documentation should always be close to its definition (usually in the .c
138or .cc files) and not its declaration, so that when the code changes it's
139less likely that they will get out of sync. For data types, macros and
140similar where there's only declarations, the documentation will usually
141go instead in the header files.
142
143For enum values and struct members, the documentation should usually be
144one-line comments, preceding the item.
145
146The comment title should be on the second line on its own, and the long
147description on its own paragraph.
148
149Examples:
150
151/**
152 * This is the enum title.
153 */
154enum value_list {
155 /** Value doing foo. */
156 VALUE_A,
157 /** Value doing bar. */
158 VALUE_B,
159};
160
161/**
162 * This is the title.
163 *
164 * This is the long description extending several lines, explaining in
165 * detail what this item does.
166 *
167 * @param a This is the a parameter.
168 * @param b This is the b parameter.
169 *
170 * @return This is the return value.
171 */
172
173Indentation, alignment and spacing
174~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
175
176Lines should be 80 chars max. Indentation is done with hard tabs (which
177should be considered to take 8 spaces width). Aligning with spaces:
178
179static void
180function(void *ptr, int value)
181{
182 void *ref_ptr = get_ref(ptr);
183 int ref_value = get_value(ref);
184
185 if (value > 10)
186 do_something(GLOBAL_MACRO, ptr, value, "some-string",
187 ref_ptr, ref_value, "other-string",
188 "extra-string");
189}
190
191When wrapping, logical operators should be kept on the preceding line:
192
193 if (really_long_variable_to_be_checked_against_a &&
194 really_long_variable_to_be_checked_against_b)
195 foo();
196
197Spaces between operators:
198
199 if (a && (b || c) && c == d)
200 break;
201
202 a = (b + 4 * (5 - 6)) & 0xff;
203
204Spaces between assignments:
205
206 a += b;
207
208Spaces after comma:
209
210 foo(a, b);
211
212Space after keywords (for, while, do, if, etc, but sizeof should be
213treated like a function):
214
215 for (i = 0; i < 10; i++)
216 foo(i);
217
218 memcpy(dst, src, sizeof(src));
219
220Definition of local variables, related code blocks, functions bodies
221should be split with blank lines:
222
223int
224function(void)
225{
226 int a;
227
228 foo();
229 bar();
230
231 quux();
232
233 return 0;
234}
235
236Braces
237~~~~~~
238
239Braces should be placed on the same line as the keyword, but on a new line
240for the function body. No braces should be used for unambiguous one line
241statements:
242
243 if (a > 0) {
244 foo(a);
245 bar(a);
246 } else {
247 quux(0)
248 bar(0);
249 }
250
251 for (;;) {
252 foo();
253 bar();
254 }
255
256 do {
257 foo();
258 bar();
259 } while (quux());
260
261 switch (foo) {
262 case a:
263 bar();
264 break;
265 case b:
266 default:
267 baz();
268 break;
269 }
270
271Code conventions
272~~~~~~~~~~~~~~~~
273
274Prefer assigning outside of conditionals:
275
276 n = read_items();
277 if (n < 100)
278 foo();
279
280String comparisons should use comparison operators to make it easier to
281see what operation is being done:
282
283 if (strcmp(a, b) == 0)
284 foo();
285
286 if (strcmp(a, b) < 0)
287 foo();
288
289
290Dpkg Perl coding style 2016-01-29
291======================
292
293General
294~~~~~~~
295
296In general you should follow the conventions listed in perlstyle(1).
297All the code should run with the “use strict” and “use warnings” pragmas,
298and pass «DPKG_DEVEL_MODE=1 make check».
299
300Code documentation
301~~~~~~~~~~~~~~~~~~
302
303Public modules should be documented with POD (see perlpod(1)). Private
304code doesn't have to use POD, simple comment lines (starting with "#") are
305enough, but if they use POD they need to note the fact that the module is
306private in the CHANGES section and specify a version «0.xx». Public scripts
307are documented in their corresponding manual pages.
308
309Indentation, alignment and spacing
310~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
311
312Lines should be 80 chars max. The indentation level is 4 characters, and
313indentation is done with soft tabs (no hard tabs) and spaces.
314
315if ($foo) {
316 if ($bar) {
317 print "Hello\n";
318 unless ($baz) {
319 print "Who are you?\n";
320 }
321 }
322}
323
324Perl version
325~~~~~~~~~~~~
326
327We don't want to impose a too-recent Perl version, so only use features
328supported by the Perl version that is currently in Debian oldstable when
329possible. Currently that means Perl 5.14.2.
330
331Object methods
332~~~~~~~~~~~~~~
333
334Use a single line to retrieve all the arguments and use $self as name
335for the current object:
336
337sub do_something {
338 my ($self, $arg1, $arg2, %opts) = @_;
339 ...
340}
341
342Supplementary optional arguments should be named and thus stored in a
343hash.