| 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. */ |