CodingStyle

   1 LTTng-Tools Coding Style
   2
   3 Author: David Goulet
   4 Last Update: 13/11/2012
   5
   6 Tabs VS Spaces:
   7 -------------
   8
   9 Right, so our two cents in this endless war! This project uses TABS for one
  10 simple reason, the coder can choose whatever size or type his/her indentation
  11 is and can set the prefered coding style by replacing the tabs which each
  12 normally respected IDE/editor can do.
  13
  14 For vim, here is what I used:
  15
  16   set shiftwidth=4
  17   set noexpandtab
  18
  19 There is one exception for which  we use space in this project is for enum,
  20 defines and macros values indentation. For instance:
  21
  22 Use space to indent the the value so they fit when reading them all. Same goes
  23 for the #define below.
  24
  25 enum my_enum {
  26         value1     = 1,
  27         value289   = 289,
  28         ...
  29 };
  30
  31 #define DEFAULT_VALUE_OF_SOME_SORT   6
  32 #define THE_ANSWER                   42
  33
  34 Use space to indent the '\' at the end but tabs at the beginning.
  35
  36 #define a_macro(x)      \
  37         do {                \
  38                 fsync();        \
  39         } while (0);        \
  40
  41 It's really the only time we use spaces. For everything else, there is TABS! :)
  42
  43 Here is a pretty cool vim macro that will highlight your whitespaces and spaces
  44 before tab. This helps a *LOT* when coding.
  45
  46 " Show trailing whitepace and spaces before a tab:
  47 function MyTrail()
  48     let no_hl_trail = ["man", "help"]
  49     if index(no_hl_trail, &ft) >= 0
  50         return
  51     endif
  52     syn match ErrorMsg /\s\+$\| \+\ze\t\|\t\+\ze / containedin=@NoTrail
  53 endfunction
  54 syn cluster NoTrail contains=ALL remove=cComment
  55 autocmd Syntax * call MyTrail()
  56
  57 C Style:
  58 -------------
  59
  60 The coding style used for this project follows the the Linux kernel guide
  61 lines, except that brackets "{", "}" should typically be used even for
  62 single-line if/else statements. Please refer to:
  63
  64 - doc/kernel-CodingStyle.txt (copied from Linux 3.4.4 git tree).
  65
  66 - Linux kernel scripts/checkpatch.pl for a script which verify the patch
  67   coding style.
  68
  69 For header files, please declare the following in this order:
  70
  71 1) #defines
  72         - Default values should go in: src/common/defaults.h
  73         - Macros used across the project: src/common/macros.h
  74
  75 2) Variables
  76         - No _static_ in a header file! This is madness.
  77         - Use _extern_ if the global variable is set else where.
  78
  79 3) Function prototype
  80
  81 Furthermore, respect the name spacing of files for each non-static symbol
  82 visiable outside the scope of the C file. For instance, for the utils.c file in
  83 libcommon, every call should be prefixed by "utils_*".
  84
  85 Error handling:
  86 -------------
  87
  88 We ask to use one single return point in a function. For that, we uses the
  89 "goto" statement for the error handling creating one single point for error
  90 handling and return code. See the following example:
  91
  92 int some_function(...)
  93 {
  94         int ret;
  95         [...]
  96
  97         if (ret != 0) {
  98                 goto error;
  99         }
 100
 101         [...]
 102 error:
 103         return ret;
 104 }
 105
 106 Commenting:
 107 -------------
 108
 109 Every function MUST have a comment above it even if the function is trivial.
 110
 111 Please add non-trivial comments/documentation as much as you can in the code.
 112 Poor comments WILL be rejected upon merging so please pay attention to this
 113 details because we do!
 114
 115 If the comments requires more than one line, please format like so:
 116
 117 /*
 118  * Some comments which requires multiple
 119  * lines [...]
 120  */
 121
 122 and on a single line:
 123
 124 /* My comment on a single line. */