doc/coding-style.txt

   1 Dpkg POD coding style 2021-06-25
   2 =====================
   3
   4 General
   5 ~~~~~~~
   6
   7 Verbatim code sections that need to be formatted, need to be prefixed with
   8 a line containing exactly «Z<>», to trick the parser.
   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 2016-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 brings one
  33 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 Standards
  75 ~~~~~~~~~
  76
  77 The C code base assumes C99, except for the following features:
  78
  79  - Variable length arrays.
  80  - Mixed declaration and code.
  81
  82 The C++ code base assumes C++03, plus the following C++11 extension:
  83
  84  + Null pointer keyword (nullptr).
  85
  86 The code base assumes a POSIX.1-2008 compatible environment.
  87
  88 The required features are checked at build time, and it will either use
  89 compatibility code in case the needed extensions are not supported and it
  90 is possible to support them, otherwise it will abort in case a needed one
  91 cannot be used.
  92
  93 General
  94 ~~~~~~~
  95
  96 The coding style is a mix of parts from KNF [K] and the Linux CodingStyle [L].
  97 If in doubt or missing from this file please ask, although files using the
  98 tab based indentation can be considered canon.
  99
 100   [K] <https://www.freebsd.org/cgi/man.cgi?query=style>
 101   [L] <https://www.kernel.org/doc/Documentation/CodingStyle>
 102
 103 The code has a mix of an old coding style being phased out and the new
 104 style. New files should use the new style, changes to files with the old
 105 style should switch the code being touched except for the indentation level,
 106 which should be preserved to match (2 spaces).
 107
 108 Code should generally strive for clarity. Monster functions should be split
 109 into logical and small pieces.
 110
 111 Variable and function names should be generally descriptive, not needed
 112 for variables commonly used (for example an index inside a loop, etc),
 113 acronyms should only be used if they are widely known externally or
 114 inside the project. The names should separate logical concepts within
 115 with underscores.
 116
 117 On comments use UTF-8 characters for quotes, copyright symbols, etc.
 118
 119 On strings in code use simple or double quotes «''» «""». Not the unpaired
 120 ones «`'». Strings marked for translation, should only be fixed if there's
 121 other changes to be done on them, otherwise we get unneeded fuzzies.
 122
 123   <https://www.cl.cam.ac.uk/~mgk25/ucs/quotes.html>
 124
 125 Code documentation
 126 ~~~~~~~~~~~~~~~~~~
 127
 128 Public declarations should be documented using JavaDoc style comments.
 129
 130 Documentation should always be close to its definition (usually in the .c
 131 or .cc files) and not its declaration, so that when the code changes it's
 132 less likely that they will get out of sync. For data types, macros and
 133 similar where there's only declarations, the documentation will usually
 134 go instead in the header files.
 135
 136 For enum values and struct members, the documentation should usually be
 137 one-line comments, preceding the item.
 138
 139 The comment title should be on the second line on its own, and the long
 140 description on its own paragraph.
 141
 142 Examples:
 143
 144 /**
 145  * This is the enum title.
 146  */
 147 enum value_list {
 148         /** Value doing foo. */
 149         VALUE_A,
 150         /** Value doing bar. */
 151         VALUE_B,
 152 };
 153
 154 /**
 155  * This is the title.
 156  *
 157  * This is the long description extending several lines, explaining in
 158  * detail what this item does.
 159  *
 160  * @param a This is the a parameter.
 161  * @param b This is the b parameter.
 162  *
 163  * @return This is the return value.
 164  */
 165
 166 Indentation, alignment and spacing
 167 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 168
 169 Lines should be 80 chars max. Indentation is done with hard tabs (which
 170 should be considered to take 8 spaces width). Aligning with spaces:
 171
 172 static void
 173 function(void *ptr, int value)
 174 {
 175         void *ref_ptr = get_ref(ptr);
 176         int ref_value = get_value(ref);
 177
 178         if (value > 10)
 179                 do_something(GLOBAL_MACRO, ptr, value, "some-string",
 180                              ref_ptr, ref_value, "other-string",
 181                              "extra-string");
 182 }
 183
 184 When wrapping, logical operators should be kept on the preceding line:
 185
 186         if (really_long_variable_to_be_checked_against_a &&
 187             really_long_variable_to_be_checked_against_b)
 188                 foo();
 189
 190 Spaces around operators:
 191
 192         if (a && (b || c) && c == d)
 193                 break;
 194
 195         a = (b + 4 * (5 - 6)) & 0xff;
 196
 197 Spaces around assignments:
 198
 199         a += b;
 200
 201 Spaces after comma:
 202
 203         foo(a, b);
 204
 205 Space after keywords (for, while, do, if, etc, but sizeof should be
 206 treated like a function):
 207
 208         for (i = 0; i < 10; i++)
 209                 foo(i);
 210
 211         memcpy(dst, src, sizeof(src));
 212
 213 Definition of local variables, related code blocks, functions bodies
 214 should be split with blank lines:
 215
 216 int
 217 function(void)
 218 {
 219         int a;
 220
 221         foo();
 222         bar();
 223
 224         quux();
 225
 226         return 0;
 227 }
 228
 229 Braces
 230 ~~~~~~
 231
 232 Braces should be placed on the same line as the keyword, but on a new line
 233 for the function body. No braces should be used for unambiguous one line
 234 statements:
 235
 236         if (a > 0) {
 237                 foo(a);
 238                 bar(a);
 239         } else {
 240                 quux(0)
 241                 bar(0);
 242         }
 243
 244         for (;;) {
 245                 foo();
 246                 bar();
 247         }
 248
 249         do {
 250                 foo();
 251                 bar();
 252         } while (quux());
 253
 254         switch (foo) {
 255         case a:
 256                 bar();
 257                 break;
 258         case b:
 259         default:
 260                 baz();
 261                 break;
 262         }
 263
 264 Code conventions
 265 ~~~~~~~~~~~~~~~~
 266
 267 Prefer assigning outside of conditionals:
 268
 269         n = read_items();
 270         if (n < 100)
 271                 foo();
 272
 273 String comparisons should use comparison operators to make it easier to
 274 see what operation is being done:
 275
 276         if (strcmp(a, b) == 0)
 277                 foo();
 278
 279         if (strcmp(a, b) < 0)
 280                 foo();
 281
 282
 283 Dpkg Perl coding style 2019-03-27
 284 ======================
 285
 286 Perl version
 287 ~~~~~~~~~~~~
 288
 289 We don't want to impose a too-recent Perl version, so only use features
 290 supported by the Perl version that is currently in Debian oldstable when
 291 possible. Currently that means Perl 5.32.1.
 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 «make authorcheck».
 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 Object methods
 325 ~~~~~~~~~~~~~~
 326
 327 Use a single line to retrieve all the arguments and use $self as name
 328 for the current object:
 329
 330 sub do_something {
 331     my ($self, $arg1, $arg2, %opts) = @_;
 332     ...
 333 }
 334
 335 Supplementary optional arguments should be named and thus stored in a
 336 hash.