doc/coding-style.txt

   1 Dpkg C coding style 2012-05-24
   2 ===================
   3
   4 C language extensions
   5 ~~~~~~~~~~~~~~~~~~~~~
   6
   7 The code base assumes C89 plus the following C99 extensions:
   8
   9  * Named initializers.
  10  * Trailing comma in enum.
  11  * Variadic macros.
  12  * Working bool type in <stdbool.h>.
  13  * Working %j and %z printf modifiers.
  14  * Magic __func__ variable.
  15
  16 Those are checked at build time, and it will abort in case a needed extension
  17 is not supported.
  18
  19 General
  20 ~~~~~~~
  21
  22 The coding style is a mix of parts from KNF [K] and the Linux CodingStyle [L].
  23 If in doubt or missing from this file please ask, although files using the
  24 tab based indentation can be considered canon.
  25
  26   [K] <http://www.freebsd.org/cgi/man.cgi?query=style>
  27   [L] <http://www.kernel.org/doc/Documentation/CodingStyle>
  28
  29 The code has a mix of an old coding style being phased out and the new
  30 style. New files should use the new style, changes to files with the old
  31 style should switch the code being touched except for the indentation level,
  32 which should be preserved to match (2 spaces).
  33
  34 Code should generally strive for clarity. Monster functions should be split
  35 into logical and small pieces.
  36
  37 Variable and function names should be generally descriptive, not needed
  38 for variables commonly used (for example an index inside a loop, etc),
  39 acronyms should only be used if they are widely known externally or
  40 inside the project. The names should separate logical concepts within
  41 with underscores.
  42
  43 On comments use UTF-8 characters for quotes, copyright symbols, etc.
  44
  45 On strings in code use simple or double quotes «''» «""». Not the unpaired
  46 ones «`'». Strings marked for translation, should only be fixed if there's
  47 other changes to be done on them, otherwise we get unneeded fuzzies.
  48
  49   <http://www.cl.cam.ac.uk/~mgk25/ucs/quotes.html>
  50
  51 Code documentation
  52 ~~~~~~~~~~~~~~~~~~
  53
  54 Public declarations should be documented using JavaDoc style comments.
  55
  56 Documentation should always be close to its definition (usually in the .c
  57 or .cc files) and not its declaration, so that when the code changes it's
  58 less likely that they will get out of sync. For data types, macros and
  59 similar where there's only declarations, the documentation will usually
  60 go instead in the header files.
  61
  62 For enum values and struct members, the documentation should usually be
  63 one-line comments, preceding the item.
  64
  65 The comment title should be on the second line on its own, and the long
  66 description on its own paragraph.
  67
  68 Examples:
  69
  70 /**
  71  * This is the enum title.
  72  */
  73 enum value_list {
  74         /** Value doing foo. */
  75         value_a,
  76         /** Value doing bar. */
  77         value_b,
  78 };
  79
  80 /**
  81  * This is the title.
  82  *
  83  * This is the long description extending several lines, explaining in
  84  * detail what this item does.
  85  *
  86  * @param a This is the a parameter.
  87  * @param b This is the b parameter.
  88  *
  89  * @return This is the return value.
  90  */
  91
  92 Indentation, alignment and spacing
  93 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  94
  95 Lines should be 80 chars max. Indentation is done with hard tabs (which
  96 should be considered to take 8 spaces width). Aligning with spaces:
  97
  98 static void
  99 function(void *ptr, int value)
 100 {
 101         void *ref_ptr = get_ref(ptr);
 102         int ref_value = get_value(ref);
 103
 104         if (value > 10)
 105                 do_something(GLOBAL_MACRO, ptr, value, "some-string",
 106                              ref_ptr, ref_value, "other-string",
 107                              "extra-string");
 108 }
 109
 110 When wrapping, logical operators should be kept on the preceding line:
 111
 112         if (really_long_variable_to_be_checked_against_a &&
 113             really_long_variable_to_be_checked_against_b)
 114                 foo();
 115
 116 Spaces between operators:
 117
 118         if (a && (b || c) && c == d)
 119                 break;
 120
 121         a = (b + 4 * (5 - 6)) & 0xff;
 122
 123 Spaces between assignments:
 124
 125         a += b;
 126
 127 Spaces after comma:
 128
 129         foo(a, b);
 130
 131 Space after keywords (for, while, do, if, etc, but sizeof should be
 132 treated like a function):
 133
 134         for (i = 0; i < 10; i++)
 135                 foo(i);
 136
 137         memcpy(dst, src, sizeof(src));
 138
 139 Definition of local variables, related code blocks, functions bodies
 140 should be split with blank lines:
 141
 142 int
 143 function(void)
 144 {
 145         int a;
 146
 147         foo();
 148         bar();
 149
 150         quux();
 151
 152         return 0;
 153 }
 154
 155 Braces
 156 ~~~~~~
 157
 158 Braces should be placed on the same line as the keyword, but on a new line
 159 for the function body. No braces should be used for unambiguous one line
 160 statements:
 161
 162         if (a > 0) {
 163                 foo(a);
 164                 bar(a);
 165         } else {
 166                 quux(0)
 167                 bar(0);
 168         }
 169
 170         for (;;) {
 171                 foo();
 172                 bar();
 173         }
 174
 175         do {
 176                 foo();
 177                 bar();
 178         } while (quux());
 179
 180         switch (foo) {
 181         case a:
 182                 bar();
 183                 break;
 184         case b:
 185         default:
 186                 baz();
 187                 break;
 188         }
 189
 190 Code conventions
 191 ~~~~~~~~~~~~~~~~
 192
 193 Prefer assigning outside of conditionals:
 194
 195         n = read_items();
 196         if (n < 100)
 197                 foo();
 198
 199 String comparisons should use comparison operators to make it easier to
 200 see what operation is being done:
 201
 202         if (strcmp(a, b) == 0)
 203                 foo();
 204
 205         if (strcmp(a, b) < 0)
 206                 foo();
 207
 208
 209 Dpkg Perl coding style 2013-01-04
 210 ======================
 211
 212 General
 213 ~~~~~~~
 214
 215 In general you should follow the conventions listed in perlstyle(1).
 216 All the code should run with the “use strict” and “use warnings” pragmas.
 217
 218 Code documentation
 219 ~~~~~~~~~~~~~~~~~~
 220
 221 Public modules should be documented with POD (see perlpod(1)). Private
 222 code doesn't have to use POD, simple comment lines (starting with "#") are
 223 enough. Public scripts are documented in their corresponding manual pages.
 224
 225 Indentation, alignment and spacing
 226 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 227
 228 Lines should be 80 chars max. The indentation level is 4 characters, and
 229 indentation is done with hard tabs (which should be considered to take 8
 230 spaces width) and spaces.
 231
 232 if ($foo) {
 233     if ($bar) {
 234         print "Hello\n";
 235         unless ($baz) {
 236             print "Who are you?\n";
 237         }
 238     }
 239 }
 240
 241 Perl version
 242 ~~~~~~~~~~~~
 243
 244 We don't want to impose a too-recent Perl version, so only use features
 245 supported by the Perl version that is currently in Debian oldstable when
 246 possible. Currently that means Perl 5.10.0.
 247
 248 Object methods
 249 ~~~~~~~~~~~~~~
 250
 251 Use a single line to retrieve all the arguments and use $self as name
 252 for the current object:
 253
 254 sub do_something {
 255     my ($self, $arg1, $arg2, %opts) = @_;
 256     ...
 257 }
 258
 259 Supplementary optional arguments should be named and thus stored in a
 260 hash.