summaryrefslogtreecommitdiffstats
path: root/doc/coding-style.txt
blob: d2e2b90712bedfabe50cad82b67e33b3cf7660bc (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
Dpkg troff coding style 2016-01-29
=======================

General
~~~~~~~

Dashes that are relevant when copy & pasted need to be escaped (e.g. those
present in program, file, argument and field names).

New sentences inside a paragraph should start on a new line, so that we
do not need to reflow the text when adding new content.

Every new feature, option or behavior change needs to be documented with
the version introducing the change.


Dpkg M4sh/Autoconf coding style 2016-09-05
===============================

General
~~~~~~~

All dpkg specific macros need to be prefixed with «DPKG_». Complex checks
should be defined as new macros under m4/dpkg-<name>.m4, and those used
in configure.ac which should look pretty simple.

Quoting and indentation
~~~~~~~~~~~~~~~~~~~~~~~

Code and arguments that wrap into the next line are indented by two spaces.

In principle all macro argument should always be quoted. Which gives brings
one of the biggest readability issues with M4sh/Autoconf code, the amount of
consecutive quotes and parenthesis pairs, which can make it very hard to
notice if they are unbalanced. To avoid this we use a style that tries to
avoid more than two consecutive blocks of «])».

We can either use a style resembling very simple function calls, when the
arguments are as well very simple, such as:

  AC_DEFINE_UNQUOTED([SOME_VARIABLE],
    [SOME_CONCOCTED_WAY_TO_GET_A_VALUE],
    [Some descriptive text here])

  AS_CASE([condition],
    [case-a], [do-a],
    [case-b], [do-b])

Or one resembling curly-braced C-style blocks, such as this:

  AS_IF([condition], [
    DO_SOMETHING([here])
  ], [
    DO_OTHERWISE([there])
  ])

Except for AC_ARG_WITH, AC_ARG_ENABLE and AM_CONDITIONAL which need their
second argument quoted tightly surrounding the code, like this:

  AC_ARG_ENABLE([feature],
    [AS_HELP_STRING([--disable-feature], [Disable feature])],
    [], [enable_feature="yes"])

  AM_CONDITIONAL([HAVE_SOME_FEATURE],
    [test "x$ac_cv_have_some_feature" = "xyes" && \
     test "x$ac_cv_have_some_feature" = "xyes"])

or the output will get messed up.


Dpkg C/C++ coding style 2016-01-29
=======================

C language extensions
~~~~~~~~~~~~~~~~~~~~~

The code base assumes C89 plus the following C99 extensions:

 * Designated initializers.
 * Compound literals.
 * Trailing comma in enum.
 * Variadic macros.
 * Working bool type in <stdbool.h>.
 * Working %j and %z printf modifiers.
 * Magic __func__ variable.

Those are checked at build time, and it will abort in case a needed extension
is not supported.

C++ language extensions
~~~~~~~~~~~~~~~~~~~~~~~

The code base assumes C++03 plus the following C++11 extension:

 * Null pointer keyword (nullptr).

This is checked at build time, and it will use compatibility code in case the
needed extension is not supported.

General
~~~~~~~

The coding style is a mix of parts from KNF [K] and the Linux CodingStyle [L].
If in doubt or missing from this file please ask, although files using the
tab based indentation can be considered canon.

  [K] <https://www.freebsd.org/cgi/man.cgi?query=style>
  [L] <https://www.kernel.org/doc/Documentation/CodingStyle>

The code has a mix of an old coding style being phased out and the new
style. New files should use the new style, changes to files with the old
style should switch the code being touched except for the indentation level,
which should be preserved to match (2 spaces).

Code should generally strive for clarity. Monster functions should be split
into logical and small pieces.

Variable and function names should be generally descriptive, not needed
for variables commonly used (for example an index inside a loop, etc),
acronyms should only be used if they are widely known externally or
inside the project. The names should separate logical concepts within
with underscores.

On comments use UTF-8 characters for quotes, copyright symbols, etc.

On strings in code use simple or double quotes «''» «""». Not the unpaired
ones «`'». Strings marked for translation, should only be fixed if there's
other changes to be done on them, otherwise we get unneeded fuzzies.

  <https://www.cl.cam.ac.uk/~mgk25/ucs/quotes.html>

Code documentation
~~~~~~~~~~~~~~~~~~

Public declarations should be documented using JavaDoc style comments.

Documentation should always be close to its definition (usually in the .c
or .cc files) and not its declaration, so that when the code changes it's
less likely that they will get out of sync. For data types, macros and
similar where there's only declarations, the documentation will usually
go instead in the header files.

For enum values and struct members, the documentation should usually be
one-line comments, preceding the item.

The comment title should be on the second line on its own, and the long
description on its own paragraph.

Examples:

/**
 * This is the enum title.
 */
enum value_list {
	/** Value doing foo. */
	VALUE_A,
	/** Value doing bar. */
	VALUE_B,
};

/**
 * This is the title.
 *
 * This is the long description extending several lines, explaining in
 * detail what this item does.
 *
 * @param a This is the a parameter.
 * @param b This is the b parameter.
 *
 * @return This is the return value.
 */

Indentation, alignment and spacing
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Lines should be 80 chars max. Indentation is done with hard tabs (which
should be considered to take 8 spaces width). Aligning with spaces:

static void
function(void *ptr, int value)
{
	void *ref_ptr = get_ref(ptr);
	int ref_value = get_value(ref);

	if (value > 10)
		do_something(GLOBAL_MACRO, ptr, value, "some-string",
		             ref_ptr, ref_value, "other-string",
		             "extra-string");
}

When wrapping, logical operators should be kept on the preceding line:

	if (really_long_variable_to_be_checked_against_a &&
	    really_long_variable_to_be_checked_against_b)
		foo();

Spaces between operators:

	if (a && (b || c) && c == d)
		break;

	a = (b + 4 * (5 - 6)) & 0xff;

Spaces between assignments:

	a += b;

Spaces after comma:

	foo(a, b);

Space after keywords (for, while, do, if, etc, but sizeof should be
treated like a function):

	for (i = 0; i < 10; i++)
		foo(i);

	memcpy(dst, src, sizeof(src));

Definition of local variables, related code blocks, functions bodies
should be split with blank lines:

int
function(void)
{
	int a;

	foo();
	bar();

	quux();

	return 0;
}

Braces
~~~~~~

Braces should be placed on the same line as the keyword, but on a new line
for the function body. No braces should be used for unambiguous one line
statements:

	if (a > 0) {
		foo(a);
		bar(a);
	} else {
		quux(0)
		bar(0);
	}

	for (;;) {
		foo();
		bar();
	}

	do {
		foo();
		bar();
	} while (quux());

	switch (foo) {
	case a:
		bar();
		break;
	case b:
	default:
		baz();
		break;
	}

Code conventions
~~~~~~~~~~~~~~~~

Prefer assigning outside of conditionals:

	n = read_items();
	if (n < 100)
		foo();

String comparisons should use comparison operators to make it easier to
see what operation is being done:

	if (strcmp(a, b) == 0)
		foo();

	if (strcmp(a, b) < 0)
		foo();


Dpkg Perl coding style 2019-03-27
======================

General
~~~~~~~

In general you should follow the conventions listed in perlstyle(1).
All the code should run with the “use strict” and “use warnings” pragmas,
and pass «DPKG_DEVEL_MODE=1 make check».

Code documentation
~~~~~~~~~~~~~~~~~~

Public modules should be documented with POD (see perlpod(1)). Private
code doesn't have to use POD, simple comment lines (starting with "#") are
enough, but if they use POD they need to note the fact that the module is
private in the CHANGES section and specify a version «0.xx». Public scripts
are documented in their corresponding manual pages.

Indentation, alignment and spacing
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Lines should be 80 chars max. The indentation level is 4 characters, and
indentation is done with soft tabs (no hard tabs) and spaces.

if ($foo) {
    if ($bar) {
        print "Hello\n";
        unless ($baz) {
            print "Who are you?\n";
        }
    }
}

Perl version
~~~~~~~~~~~~

We don't want to impose a too-recent Perl version, so only use features
supported by the Perl version that is currently in Debian oldstable when
possible. Currently that means Perl 5.24.1.

Object methods
~~~~~~~~~~~~~~

Use a single line to retrieve all the arguments and use $self as name
for the current object:

sub do_something {
    my ($self, $arg1, $arg2, %opts) = @_;
    ...
}

Supplementary optional arguments should be named and thus stored in a
hash.