Commit | Line | Data |
---|---|---|
1479465f GJ |
1 | Dpkg troff coding style 2016-01-29 |
2 | ======================= | |
3 | ||
4 | General | |
5 | ~~~~~~~ | |
6 | ||
7 | Dashes that are relevant when copy & pasted need to be escaped (e.g. those | |
8 | present in program, file, argument and field names). | |
9 | ||
10 | New sentences inside a paragraph should start on a new line, so that we | |
11 | do not need to reflow the text when adding new content. | |
12 | ||
13 | Every new feature, option or behavior change needs to be documented with | |
14 | the version introducing the change. | |
15 | ||
16 | ||
17 | Dpkg M4sh/Autoconf coding style 1016-09-05 | |
18 | =============================== | |
19 | ||
20 | General | |
21 | ~~~~~~~ | |
22 | ||
23 | All dpkg specific macros need to be prefixed with «DPKG_». Complex checks | |
24 | should be defined as new macros under m4/dpkg-<name>.m4, and those used | |
25 | in configure.ac which should look pretty simple. | |
26 | ||
27 | Quoting and indentation | |
28 | ~~~~~~~~~~~~~~~~~~~~~~~ | |
29 | ||
30 | Code and arguments that wrap into the next line are indented by two spaces. | |
31 | ||
32 | In principle all macro argument should always be quoted. Which gives brings | |
33 | one of the biggest readability issues with M4sh/Autoconf code, the amount of | |
34 | consecutive quotes and parenthesis pairs, which can make it very hard to | |
35 | notice if they are unbalanced. To avoid this we use a style that tries to | |
36 | avoid more than two consecutive blocks of «])». | |
37 | ||
38 | We can either use a style resembling very simple function calls, when the | |
39 | arguments 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 | ||
49 | Or 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 | ||
57 | Except for AC_ARG_WITH, AC_ARG_ENABLE and AM_CONDITIONAL which need their | |
58 | second 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 | ||
68 | or the output will get messed up. | |
69 | ||
70 | ||
71 | Dpkg C/C++ coding style 2016-01-29 | |
72 | ======================= | |
73 | ||
74 | C language extensions | |
75 | ~~~~~~~~~~~~~~~~~~~~~ | |
76 | ||
77 | The 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 | ||
87 | Those are checked at build time, and it will abort in case a needed extension | |
88 | is not supported. | |
89 | ||
90 | C++ language extensions | |
91 | ~~~~~~~~~~~~~~~~~~~~~~~ | |
92 | ||
93 | The code base assumes C++03 plus the following C++11 extension: | |
94 | ||
95 | * Null pointer keyword (nullptr). | |
96 | ||
97 | This is checked at build time, and it will use compatibility code in case the | |
98 | needed extension is not supported. | |
99 | ||
100 | General | |
101 | ~~~~~~~ | |
102 | ||
103 | The coding style is a mix of parts from KNF [K] and the Linux CodingStyle [L]. | |
104 | If in doubt or missing from this file please ask, although files using the | |
105 | tab 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 | ||
110 | The code has a mix of an old coding style being phased out and the new | |
111 | style. New files should use the new style, changes to files with the old | |
112 | style should switch the code being touched except for the indentation level, | |
113 | which should be preserved to match (2 spaces). | |
114 | ||
115 | Code should generally strive for clarity. Monster functions should be split | |
116 | into logical and small pieces. | |
117 | ||
118 | Variable and function names should be generally descriptive, not needed | |
119 | for variables commonly used (for example an index inside a loop, etc), | |
120 | acronyms should only be used if they are widely known externally or | |
121 | inside the project. The names should separate logical concepts within | |
122 | with underscores. | |
123 | ||
124 | On comments use UTF-8 characters for quotes, copyright symbols, etc. | |
125 | ||
126 | On strings in code use simple or double quotes «''» «""». Not the unpaired | |
127 | ones «`'». Strings marked for translation, should only be fixed if there's | |
128 | other changes to be done on them, otherwise we get unneeded fuzzies. | |
129 | ||
130 | <https://www.cl.cam.ac.uk/~mgk25/ucs/quotes.html> | |
131 | ||
132 | Code documentation | |
133 | ~~~~~~~~~~~~~~~~~~ | |
134 | ||
135 | Public declarations should be documented using JavaDoc style comments. | |
136 | ||
137 | Documentation should always be close to its definition (usually in the .c | |
138 | or .cc files) and not its declaration, so that when the code changes it's | |
139 | less likely that they will get out of sync. For data types, macros and | |
140 | similar where there's only declarations, the documentation will usually | |
141 | go instead in the header files. | |
142 | ||
143 | For enum values and struct members, the documentation should usually be | |
144 | one-line comments, preceding the item. | |
145 | ||
146 | The comment title should be on the second line on its own, and the long | |
147 | description on its own paragraph. | |
148 | ||
149 | Examples: | |
150 | ||
151 | /** | |
152 | * This is the enum title. | |
153 | */ | |
154 | enum 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 | ||
173 | Indentation, alignment and spacing | |
174 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
175 | ||
176 | Lines should be 80 chars max. Indentation is done with hard tabs (which | |
177 | should be considered to take 8 spaces width). Aligning with spaces: | |
178 | ||
179 | static void | |
180 | function(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 | ||
191 | When 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 | ||
197 | Spaces between operators: | |
198 | ||
199 | if (a && (b || c) && c == d) | |
200 | break; | |
201 | ||
202 | a = (b + 4 * (5 - 6)) & 0xff; | |
203 | ||
204 | Spaces between assignments: | |
205 | ||
206 | a += b; | |
207 | ||
208 | Spaces after comma: | |
209 | ||
210 | foo(a, b); | |
211 | ||
212 | Space after keywords (for, while, do, if, etc, but sizeof should be | |
213 | treated like a function): | |
214 | ||
215 | for (i = 0; i < 10; i++) | |
216 | foo(i); | |
217 | ||
218 | memcpy(dst, src, sizeof(src)); | |
219 | ||
220 | Definition of local variables, related code blocks, functions bodies | |
221 | should be split with blank lines: | |
222 | ||
223 | int | |
224 | function(void) | |
225 | { | |
226 | int a; | |
227 | ||
228 | foo(); | |
229 | bar(); | |
230 | ||
231 | quux(); | |
232 | ||
233 | return 0; | |
234 | } | |
235 | ||
236 | Braces | |
237 | ~~~~~~ | |
238 | ||
239 | Braces should be placed on the same line as the keyword, but on a new line | |
240 | for the function body. No braces should be used for unambiguous one line | |
241 | statements: | |
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 | ||
271 | Code conventions | |
272 | ~~~~~~~~~~~~~~~~ | |
273 | ||
274 | Prefer assigning outside of conditionals: | |
275 | ||
276 | n = read_items(); | |
277 | if (n < 100) | |
278 | foo(); | |
279 | ||
280 | String comparisons should use comparison operators to make it easier to | |
281 | see 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 | ||
290 | Dpkg Perl coding style 2016-01-29 | |
291 | ====================== | |
292 | ||
293 | General | |
294 | ~~~~~~~ | |
295 | ||
296 | In general you should follow the conventions listed in perlstyle(1). | |
297 | All the code should run with the “use strict” and “use warnings” pragmas, | |
298 | and pass «DPKG_DEVEL_MODE=1 make check». | |
299 | ||
300 | Code documentation | |
301 | ~~~~~~~~~~~~~~~~~~ | |
302 | ||
303 | Public modules should be documented with POD (see perlpod(1)). Private | |
304 | code doesn't have to use POD, simple comment lines (starting with "#") are | |
305 | enough, but if they use POD they need to note the fact that the module is | |
306 | private in the CHANGES section and specify a version «0.xx». Public scripts | |
307 | are documented in their corresponding manual pages. | |
308 | ||
309 | Indentation, alignment and spacing | |
310 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
311 | ||
312 | Lines should be 80 chars max. The indentation level is 4 characters, and | |
313 | indentation is done with soft tabs (no hard tabs) and spaces. | |
314 | ||
315 | if ($foo) { | |
316 | if ($bar) { | |
317 | print "Hello\n"; | |
318 | unless ($baz) { | |
319 | print "Who are you?\n"; | |
320 | } | |
321 | } | |
322 | } | |
323 | ||
324 | Perl version | |
325 | ~~~~~~~~~~~~ | |
326 | ||
327 | We don't want to impose a too-recent Perl version, so only use features | |
328 | supported by the Perl version that is currently in Debian oldstable when | |
329 | possible. Currently that means Perl 5.14.2. | |
330 | ||
331 | Object methods | |
332 | ~~~~~~~~~~~~~~ | |
333 | ||
334 | Use a single line to retrieve all the arguments and use $self as name | |
335 | for the current object: | |
336 | ||
337 | sub do_something { | |
338 | my ($self, $arg1, $arg2, %opts) = @_; | |
339 | ... | |
340 | } | |
341 | ||
342 | Supplementary optional arguments should be named and thus stored in a | |
343 | hash. |