mdw@git.distorted.org.uk Git - dpkg/blob - doc/coding-style.txt

   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.