git.cworth.org Git - notmuch/blob - devel/STYLE

   1 C/C++ coding style
   2 ==================
   3
   4 Tools
   5 -----
   6
   7 There is a file uncrustify.cfg in this directory that can be used to
   8 approximate the prevailing code style. You can run it with e.g.
   9
  10    uncrustify --replace -c devel/uncrustify.cfg foo.c
  11
  12 You still have to use your judgement about accepting or rejecting the
  13 changes uncrustify makes. With a nice git frontend, you can add the
  14 lines you agree with and reject the rest.
  15
  16 For Emacs users, the file .dir-locals.el in the top level source
  17 directory will configure c-mode to automatically meet most of the
  18 basic layout rules.  I
  19
  20 Indentation, Whitespace, and Layout
  21 -----------------------------------
  22
  23 The following nonsense code demonstrates many aspects of the style:
  24
  25 static some_type
  26 function (param_type param, param_type param)
  27 {
  28    for (int i = 0; i < 10; i++) {
  29        int j;
  30
  31        j = i + 10;
  32
  33        some_other_func (j, i);
  34    }
  35 }
  36
  37 * Indent is 4 spaces with mixed tab/spaces and a tab width of 8.
  38   (Specifically, a line should begin with zero or more tabs followed
  39   by fewer than eight spaces.)
  40
  41 * Use copious whitespace.  In particular
  42    - there is a space between the function name and the open paren in a call.
  43    - likewise, there is a space following keywords such as if and while
  44    - every binary operator should have space on either side.
  45
  46 * No trailing whitespace. Please enable the standard pre-commit hook in git
  47   (or an equivalent hook). The standard pre-commit hook is enabled by simply
  48   renaming file '.git/hooks/pre-commit.sample' to '.git/hooks/pre-commit' .
  49
  50 * The name in a function prototype should start at the beginning of a line.
  51
  52 * Opening braces "cuddle" (they are on the same line as the
  53   if/for/while test) and are preceded by a space. The opening brace of
  54   functions is the exception, and starts on a new line.
  55
  56 * Opening parens also cuddle, even if the first argument does not fit
  57   on the same line.
  58
  59 * Ternary operators that span a line should be parenthesized like as
  60   "a ? (\n b ) : c". This is mainly to keep the indentation tools
  61   happy.
  62
  63 * Comments are always C-style /* */ block comments, with a leading *
  64   each line.  They should start with a capital letter and generally be
  65   written in complete sentences.  Public library functions are
  66   documented immediately before their prototype in lib/notmuch.h.
  67   Internal functions are typically documented immediately before their
  68   definition.
  69
  70 * Code lines should be less than 80 columns and comments should be
  71   wrapped at 70 columns.
  72
  73 * Variable declarations should be at the top of a block; C99 style
  74   control variable declarations in for loops are also OK.
  75
  76 Naming
  77 ------
  78
  79 * Use lowercase_with_underscores for function, variable, and type
  80   names.
  81
  82 * Except for variables with extremely small scope, and perhaps loop
  83   indices, when naming variables and functions, err on the side of
  84   verbosity.
  85
  86 * All structs should be typedef'd to a name ending with _t.  If the
  87   struct has a tag, it should be the same as the typedef name, minus
  88   the trailing _t.
  89
  90 CLI conventions
  91 ---------------
  92
  93 * Any changes to the JSON output format of search or show need an
  94   accompanying change to devel/schemata.
  95
  96 libnotmuch conventions
  97 ----------------------------------
  98
  99 * Functions starting with notmuch_ in lib/notmuch.h are public and are
 100   automatically exported from the shared library.  Private library
 101   functions should generally either be static or, if they are shared
 102   between compilation units, start with _notmuch.
 103
 104 * Functions in libnotmuch must not access user configuration files
 105   (i.e. .notmuch-config)
 106
 107 * Code which needs to be accessed from both the CLI and from
 108   libnotmuch should be factored out into libutil (under util/).
 109
 110 * Deprecated functions should be marked with the NOTMUCH_DEPRECATED
 111   macro which generates run time warnings with gcc and clang. In order
 112   not to confuse doxygen this should go at the beginning of the
 113   declaration like:
 114
 115   NOTMUCH_DEPRECATED(major,minor) notmuch_status_t notmuch_dwim(void *arg);
 116
 117   The @deprecated doxygen command can be used to generate markup in
 118   the API docs.