From 9a08cbfcc1ef900a04580f35afe2a4592d7d6030 Mon Sep 17 00:00:00 2001 From: Daniel Baumann Date: Mon, 6 May 2024 02:45:20 +0200 Subject: Adding upstream version 1.19.8. Signed-off-by: Daniel Baumann --- doc/coding-style.txt | 343 +++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 343 insertions(+) create mode 100644 doc/coding-style.txt (limited to 'doc/coding-style.txt') diff --git a/doc/coding-style.txt b/doc/coding-style.txt new file mode 100644 index 0000000..5e00dda --- /dev/null +++ b/doc/coding-style.txt @@ -0,0 +1,343 @@ +Dpkg troff coding style 2016-01-29 +======================= + +General +~~~~~~~ + +Dashes that are relevant when copy & pasted need to be escaped (e.g. those +present in program, file, argument and field names). + +New sentences inside a paragraph should start on a new line, so that we +do not need to reflow the text when adding new content. + +Every new feature, option or behavior change needs to be documented with +the version introducing the change. + + +Dpkg M4sh/Autoconf coding style 2016-09-05 +=============================== + +General +~~~~~~~ + +All dpkg specific macros need to be prefixed with «DPKG_». Complex checks +should be defined as new macros under m4/dpkg-.m4, and those used +in configure.ac which should look pretty simple. + +Quoting and indentation +~~~~~~~~~~~~~~~~~~~~~~~ + +Code and arguments that wrap into the next line are indented by two spaces. + +In principle all macro argument should always be quoted. Which gives brings +one of the biggest readability issues with M4sh/Autoconf code, the amount of +consecutive quotes and parenthesis pairs, which can make it very hard to +notice if they are unbalanced. To avoid this we use a style that tries to +avoid more than two consecutive blocks of «])». + +We can either use a style resembling very simple function calls, when the +arguments are as well very simple, such as: + + AC_DEFINE_UNQUOTED([SOME_VARIABLE], + [SOME_CONCOCTED_WAY_TO_GET_A_VALUE], + [Some descriptive text here]) + + AS_CASE([condition], + [case-a], [do-a], + [case-b], [do-b]) + +Or one resembling curly-braced C-style blocks, such as this: + + AS_IF([condition], [ + DO_SOMETHING([here]) + ], [ + DO_OTHERWISE([there]) + ]) + +Except for AC_ARG_WITH, AC_ARG_ENABLE and AM_CONDITIONAL which need their +second argument quoted tightly surrounding the code, like this: + + AC_ARG_ENABLE([feature], + [AS_HELP_STRING([--disable-feature], [Disable feature])], + [], [enable_feature="yes"]) + + AM_CONDITIONAL([HAVE_SOME_FEATURE], + [test "x$ac_cv_have_some_feature" = "xyes" && \ + test "x$ac_cv_have_some_feature" = "xyes"]) + +or the output will get messed up. + + +Dpkg C/C++ coding style 2016-01-29 +======================= + +C language extensions +~~~~~~~~~~~~~~~~~~~~~ + +The code base assumes C89 plus the following C99 extensions: + + * Designated initializers. + * Compound literals. + * Trailing comma in enum. + * Variadic macros. + * Working bool type in . + * Working %j and %z printf modifiers. + * Magic __func__ variable. + +Those are checked at build time, and it will abort in case a needed extension +is not supported. + +C++ language extensions +~~~~~~~~~~~~~~~~~~~~~~~ + +The code base assumes C++03 plus the following C++11 extension: + + * Null pointer keyword (nullptr). + +This is checked at build time, and it will use compatibility code in case the +needed extension is not supported. + +General +~~~~~~~ + +The coding style is a mix of parts from KNF [K] and the Linux CodingStyle [L]. +If in doubt or missing from this file please ask, although files using the +tab based indentation can be considered canon. + + [K] + [L] + +The code has a mix of an old coding style being phased out and the new +style. New files should use the new style, changes to files with the old +style should switch the code being touched except for the indentation level, +which should be preserved to match (2 spaces). + +Code should generally strive for clarity. Monster functions should be split +into logical and small pieces. + +Variable and function names should be generally descriptive, not needed +for variables commonly used (for example an index inside a loop, etc), +acronyms should only be used if they are widely known externally or +inside the project. The names should separate logical concepts within +with underscores. + +On comments use UTF-8 characters for quotes, copyright symbols, etc. + +On strings in code use simple or double quotes «''» «""». Not the unpaired +ones «`'». Strings marked for translation, should only be fixed if there's +other changes to be done on them, otherwise we get unneeded fuzzies. + + + +Code documentation +~~~~~~~~~~~~~~~~~~ + +Public declarations should be documented using JavaDoc style comments. + +Documentation should always be close to its definition (usually in the .c +or .cc files) and not its declaration, so that when the code changes it's +less likely that they will get out of sync. For data types, macros and +similar where there's only declarations, the documentation will usually +go instead in the header files. + +For enum values and struct members, the documentation should usually be +one-line comments, preceding the item. + +The comment title should be on the second line on its own, and the long +description on its own paragraph. + +Examples: + +/** + * This is the enum title. + */ +enum value_list { + /** Value doing foo. */ + VALUE_A, + /** Value doing bar. */ + VALUE_B, +}; + +/** + * This is the title. + * + * This is the long description extending several lines, explaining in + * detail what this item does. + * + * @param a This is the a parameter. + * @param b This is the b parameter. + * + * @return This is the return value. + */ + +Indentation, alignment and spacing +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Lines should be 80 chars max. Indentation is done with hard tabs (which +should be considered to take 8 spaces width). Aligning with spaces: + +static void +function(void *ptr, int value) +{ + void *ref_ptr = get_ref(ptr); + int ref_value = get_value(ref); + + if (value > 10) + do_something(GLOBAL_MACRO, ptr, value, "some-string", + ref_ptr, ref_value, "other-string", + "extra-string"); +} + +When wrapping, logical operators should be kept on the preceding line: + + if (really_long_variable_to_be_checked_against_a && + really_long_variable_to_be_checked_against_b) + foo(); + +Spaces between operators: + + if (a && (b || c) && c == d) + break; + + a = (b + 4 * (5 - 6)) & 0xff; + +Spaces between assignments: + + a += b; + +Spaces after comma: + + foo(a, b); + +Space after keywords (for, while, do, if, etc, but sizeof should be +treated like a function): + + for (i = 0; i < 10; i++) + foo(i); + + memcpy(dst, src, sizeof(src)); + +Definition of local variables, related code blocks, functions bodies +should be split with blank lines: + +int +function(void) +{ + int a; + + foo(); + bar(); + + quux(); + + return 0; +} + +Braces +~~~~~~ + +Braces should be placed on the same line as the keyword, but on a new line +for the function body. No braces should be used for unambiguous one line +statements: + + if (a > 0) { + foo(a); + bar(a); + } else { + quux(0) + bar(0); + } + + for (;;) { + foo(); + bar(); + } + + do { + foo(); + bar(); + } while (quux()); + + switch (foo) { + case a: + bar(); + break; + case b: + default: + baz(); + break; + } + +Code conventions +~~~~~~~~~~~~~~~~ + +Prefer assigning outside of conditionals: + + n = read_items(); + if (n < 100) + foo(); + +String comparisons should use comparison operators to make it easier to +see what operation is being done: + + if (strcmp(a, b) == 0) + foo(); + + if (strcmp(a, b) < 0) + foo(); + + +Dpkg Perl coding style 2017-05-18 +====================== + +General +~~~~~~~ + +In general you should follow the conventions listed in perlstyle(1). +All the code should run with the “use strict” and “use warnings” pragmas, +and pass «DPKG_DEVEL_MODE=1 make check». + +Code documentation +~~~~~~~~~~~~~~~~~~ + +Public modules should be documented with POD (see perlpod(1)). Private +code doesn't have to use POD, simple comment lines (starting with "#") are +enough, but if they use POD they need to note the fact that the module is +private in the CHANGES section and specify a version «0.xx». Public scripts +are documented in their corresponding manual pages. + +Indentation, alignment and spacing +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Lines should be 80 chars max. The indentation level is 4 characters, and +indentation is done with soft tabs (no hard tabs) and spaces. + +if ($foo) { + if ($bar) { + print "Hello\n"; + unless ($baz) { + print "Who are you?\n"; + } + } +} + +Perl version +~~~~~~~~~~~~ + +We don't want to impose a too-recent Perl version, so only use features +supported by the Perl version that is currently in Debian oldstable when +possible. Currently that means Perl 5.20.2. + +Object methods +~~~~~~~~~~~~~~ + +Use a single line to retrieve all the arguments and use $self as name +for the current object: + +sub do_something { + my ($self, $arg1, $arg2, %opts) = @_; + ... +} + +Supplementary optional arguments should be named and thus stored in a +hash. -- cgit v1.2.3