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