CODING_STYLE.md

   1 # Coding style
   2
   3 - Indentation in tabs, 8 characters wide, spaces after the tabs where
   4   vertical alignment is required (see below)
   5
   6 **Note: this file uses spaces due to markdown rendering issues for tabs.
   7   Code must be implemented using tabs.**
   8
   9 - Max line width 80ch, do not break up printed strings though
  10
  11 - Break up long lines at logical groupings, one line for each logical group
  12
  13 ```c
  14 int a = somelongname() +
  15         someotherlongname();
  16
  17 if (a < 0 &&
  18     (b > 20 & d < 10) &&
  19     d != 0.0)
  20
  21
  22 somelongfunctioncall(arg1,
  23                      arg2,
  24                      arg3);
  25 ```
  26
  27 - Function declarations: return type on separate line, {} on separate line,
  28   arguments broken up as above.
  29
  30 ```c
  31 static inline int
  32 foobar(int a, int b)
  33 {
  34
  35 }
  36
  37 void
  38 somenamethatiswaytoolong(int a,
  39                          int b,
  40                          int c)
  41 {
  42 }
  43 ```
  44
  45 - `/* comments only */`, no `// comments`
  46
  47 - `variable_name`, not `VariableName` or `variableName`. same for functions.
  48
  49 - no typedefs of structs, enums, unions
  50
  51 - if it generates a compiler warning, it needs to be fixed
  52 - if it generates a static checker warning, it needs to be fixed or
  53   commented
  54
  55 - declare variables when they are used first and try to keep them as local as possible.
  56   Exception: basic loop variables, e.g. for (int i = 0; ...) should always be
  57   declared inside the loop even where multiple loops exist
  58
  59 ```c
  60 int a;
  61
  62 if (foo) {
  63         int b = 10;
  64
  65         a = get_value();
  66         usevalue(a, b);
  67 }
  68
  69 if (bar) {
  70         a = get_value();
  71         useit(a);
  72 }
  73
  74 int c = a * 100;
  75 useit(c);
  76 ```
  77
  78 - avoid uninitialized variables where possible, declare them late instead.
  79   Note that most of libinput predates this style, try to stick with the code
  80   around you if in doubt.
  81
  82   wrong:
  83
  84 ```c
  85         int *a;
  86         int b = 7;
  87
  88         ... some code ...
  89
  90         a = zalloc(32);
  91 ```
  92
  93   right:
  94
  95 ```c
  96         int b = 7;
  97         ... some code ...
  98
  99         int *a = zalloc(32);
 100 ```
 101
 102 - avoid calling non-obvious functions inside declaration blocks for multiple
 103   variables.
 104
 105   bad:
 106
 107 ```c
 108 {
 109         int a = 7;
 110         int b = some_complicated_function();
 111         int *c = zalloc(32);
 112 }
 113 ```
 114
 115   better:
 116 ```c
 117 {
 118         int a = 7;
 119         int *c = zalloc(32);
 120
 121         int b = some_complicated_function();
 122 }
 123 ```
 124
 125   There is a bit of gut-feeling involved with this, but the goal is to make
 126   the variable values immediately recognizable.
 127
 128 - Where statements are near-identical and repeated, try to keep them
 129   identical:
 130
 131   bad:
 132 ```c
 133 int a = get_some_value(x++);
 134 do_something(a);
 135 a = get_some_value(x++);
 136 do_something(a);
 137 a = get_some_value(x++);
 138 do_something(a);
 139 ```
 140   better:
 141
 142 ```c
 143 int a;
 144 a = = get_some_value(x++);
 145 do_something(a);
 146 a = get_some_value(x++);
 147 do_something(a);
 148 a = get_some_value(x++);
 149 do_something(a);
 150 ```
 151
 152 - if/else: { on the same line, no curly braces if both blocks are a single
 153   statement. If either if or else block are multiple statements, both must
 154   have curly braces.
 155
 156 ```c
 157 if (foo) {
 158         blah();
 159         bar();
 160 } else {
 161         a = 10;
 162 }
 163 ```
 164
 165 - public functions MUST be doxygen-commented, use doxygen's `@foo` rather than
 166   `\foo` notation
 167
 168 - `#include "config.h"` comes first, followed by system headers, followed by
 169   external library headers, followed by internal headers.
 170   sort alphabetically where it makes sense (specifically system headers)
 171
 172 ```c
 173 #include "config.h"
 174
 175 #include <stdio.h>
 176 #include <string.h>
 177
 178 #include <libevdev/libevdev.h>
 179
 180 #include "libinput-private.h"
 181 ```
 182
 183 - goto jumps only to the end of the function, and only for good reasons
 184   (usually cleanup). goto never jumps backwards
 185
 186 - Use stdbool.h's bool for booleans within the library (instead of `int`).
 187   Exception: the public API uses int, not bool.
 188
 189 # Git commit message requirements
 190
 191 Our CI will check the commit messages for a few requirements. Below is the
 192 list of what we expect from a git commit.
 193
 194 ## Commit message content
 195
 196 A [good commit message](http://who-t.blogspot.com/2009/12/on-commit-messages.html) needs to
 197 answer three questions:
 198
 199 - Why is it necessary? It may fix a bug, it may add a feature, it may
 200   improve performance, reliabilty, stability, or just be a change for the
 201   sake of correctness.
 202 - How does it address the issue? For short obvious patches this part can be
 203   omitted, but it should be a high level description of what the approach
 204   was.
 205 - What effects does the patch have? (In addition to the obvious ones, this
 206   may include benchmarks, side effects, etc.)
 207
 208 These three questions establish the context for the actual code changes, put
 209 reviewers and others into the frame of mind to look at the diff and check if
 210 the approach chosen was correct. A good commit message also helps
 211 maintainers to decide if a given patch is suitable for stable branches or
 212 inclusion in a distribution.
 213
 214 ## Developer Certificate of Origin
 215
 216 Your commit **must** be signed off with a line:
 217 ```
 218 Signed-off-by: <your name> <your email address>
 219 ```
 220 By signing off, you indicate the [developer certificate of origin](https://developercertificate.org/).
 221
 222 > By making a contribution to this project, I certify that:
 223 >
 224 > (a) The contribution was created in whole or in part by me and I
 225 >     have the right to submit it under the open source license
 226 >     indicated in the file; or
 227 >
 228 > (b) The contribution is based upon previous work that, to the best
 229 >     of my knowledge, is covered under an appropriate open source
 230 >     license and I have the right under that license to submit that
 231 >     work with modifications, whether created in whole or in part
 232 >     by me, under the same open source license (unless I am
 233 >     permitted to submit under a different license), as indicated
 234 >     in the file; or
 235 >
 236 > (c) The contribution was provided directly to me by some other
 237 >     person who certified (a), (b) or (c) and I have not modified
 238 >     it.
 239 >
 240 > (d) I understand and agree that this project and the contribution
 241 >     are public and that a record of the contribution (including all
 242 >     personal information I submit with it, including my sign-off) is
 243 >     maintained indefinitely and may be redistributed consistent with
 244 >     this project or the open source license(s) involved.
 245
 246 ## Commit message format
 247
 248 The canonical git commit message format is:
 249
 250 ```
 251 one line as the subject line with a high-level note
 252
 253 full explanation of the patch follows after an empty line. This explanation
 254 can be multiple paragraphs and is largely free-form. Markdown is not
 255 supported.
 256
 257 You can include extra data where required like:
 258 - benchmark one says 10s
 259 - benchmark two says 12s
 260
 261 Signed-off-by: <your name> <your email>
 262 ```
 263
 264 The subject line is the first thing everyone sees about this commit, so make
 265 sure it's on point.
 266
 267 ## Commit message technical requirements
 268
 269 - The commit message should use present tense (not past tense). Do write
 270   "change foo to bar", not "changed foo to bar".
 271 - The text width of the commit should be 78 chars or less, especially the
 272   subject line.
 273 - The author and signed-off-by must be your real name and email address. We
 274   do not accept the default `@users.noreply` gitlab addresses.
 275   ```
 276   git config --global user.name Your Name
 277   git config --global user.email your@email
 278   ```