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, arg2,
  23                      otherarg);
  24 ```
  25
  26 - Function declarations: return type on separate line, {} on separate line,
  27   arguments broken up as above.
  28
  29 ```c
  30 static inline int
  31 foobar(int a, int b)
  32 {
  33
  34 }
  35
  36 void
  37 somenamethatiswaytoolong(int a, int b,
  38                          int other)
  39 {
  40 }
  41 ```
  42
  43 - `/* comments only */`, no `// comments`
  44
  45 - `variable_name`, not `VariableName` or `variableName`. same for functions.
  46
  47 - no typedefs of structs, enums, unions
  48
  49 - if it generates a compiler warning, it needs to be fixed
  50 - if it generates a static checker warning, it needs to be fixed or
  51   commented
  52
  53 - declare variables at the top, try to keep them as local as possible.
  54   Exception: if the same variable is re-used in multiple blocks, declare it
  55   at the top.
  56   Exception: basic loop variables, e.g. for (int i = 0; ...)
  57
  58 ```c
  59 int a;
  60 int c;
  61
  62 if (foo) {
  63         int b;
  64
  65         c = get_value();
  66         usevalue(c);
  67 }
  68
  69 if (bar) {
  70         c = get_value();
  71         useit(c);
  72 }
  73 ```
  74
  75 - do not mix function invocations and variable definitions.
  76
  77   wrong:
  78
  79 ```c
  80 {
  81         int a = foo();
  82         int b = 7;
  83 }
  84 ```
  85
  86   right:
  87 ```c
  88 {
  89         int a;
  90         int b = 7;
  91
  92         a = foo();
  93 }
  94 ```
  95
  96 - if/else: { on the same line, no curly braces if both blocks are a single
  97   statement. If either if or else block are multiple statements, both must
  98   have curly braces.
  99
 100 ```c
 101 if (foo) {
 102         blah();
 103         bar();
 104 } else {
 105         a = 10;
 106 }
 107 ```
 108
 109 - public functions MUST be doxygen-commented, use doxygen's `@foo` rather than
 110   `\foo` notation
 111
 112 - `#include "config.h"` comes first, followed by system headers, followed by
 113   external library headers, followed by internal headers.
 114   sort alphabetically where it makes sense (specifically system headers)
 115
 116 ```c
 117 #include "config.h"
 118
 119 #include <stdio.h>
 120 #include <string.h>
 121
 122 #include <libevdev/libevdev.h>
 123
 124 #include "libevdev-int.h"
 125 ```
 126
 127 - goto jumps only to the end of the function, and only for good reasons
 128   (usually cleanup). goto never jumps backwards
 129
 130 - Use stdbool.h's bool for booleans within the library (instead of `int`).
 131   Exception: the public API uses int, not bool.
 132
 133 # Git commit message requirements
 134
 135 Our CI will check the commit messages for a few requirements. Below is the
 136 list of what we expect from a git commit.
 137
 138 ## Commit message content
 139
 140 A [good commit message](http://who-t.blogspot.com/2009/12/on-commit-messages.html) needs to
 141 answer three questions:
 142
 143 - Why is it necessary? It may fix a bug, it may add a feature, it may
 144   improve performance, reliability, stability, or just be a change for the
 145   sake of correctness.
 146 - How does it address the issue? For short obvious patches this part can be
 147   omitted, but it should be a high level description of what the approach
 148   was.
 149 - What effects does the patch have? (In addition to the obvious ones, this
 150   may include benchmarks, side effects, etc.)
 151
 152 These three questions establish the context for the actual code changes, put
 153 reviewers and others into the frame of mind to look at the diff and check if
 154 the approach chosen was correct. A good commit message also helps
 155 maintainers to decide if a given patch is suitable for stable branches or
 156 inclusion in a distribution.
 157
 158 ## Developer Certificate of Origin
 159
 160 Your commit **must** be signed off with a line:
 161 ```
 162 Signed-off-by: <your name> <your email address>
 163 ```
 164 By signing off, you indicate the [developer certificate of origin](https://developercertificate.org/).
 165
 166 > By making a contribution to this project, I certify that:
 167 >
 168 > (a) The contribution was created in whole or in part by me and I
 169 >     have the right to submit it under the open source license
 170 >     indicated in the file; or
 171 >
 172 > (b) The contribution is based upon previous work that, to the best
 173 >     of my knowledge, is covered under an appropriate open source
 174 >     license and I have the right under that license to submit that
 175 >     work with modifications, whether created in whole or in part
 176 >     by me, under the same open source license (unless I am
 177 >     permitted to submit under a different license), as indicated
 178 >     in the file; or
 179 >
 180 > (c) The contribution was provided directly to me by some other
 181 >     person who certified (a), (b) or (c) and I have not modified
 182 >     it.
 183 >
 184 > (d) I understand and agree that this project and the contribution
 185 >     are public and that a record of the contribution (including all
 186 >     personal information I submit with it, including my sign-off) is
 187 >     maintained indefinitely and may be redistributed consistent with
 188 >     this project or the open source license(s) involved.
 189
 190 ## Commit message format
 191
 192 The canonical git commit message format is:
 193
 194 ```
 195 one line as the subject line with a high-level note
 196
 197 full explanation of the patch follows after an empty line. This explanation
 198 can be multiple paragraphs and is largely free-form. Markdown is not
 199 supported.
 200
 201 You can include extra data where required like:
 202 - benchmark one says 10s
 203 - benchmark two says 12s
 204
 205 Signed-off-by: <your name> <your email>
 206 ```
 207
 208 The subject line is the first thing everyone sees about this commit, so make
 209 sure it's on point.
 210
 211 ## Commit message technical requirements
 212
 213 - The commit message should use present tense (not past tense). Do write
 214   "change foo to bar", not "changed foo to bar".
 215 - The text width of the commit should be 78 chars or less, especially the
 216   subject line.
 217 - The author and signed-off-by must be your real name and email address. We
 218   do not accept the default `@users.noreply` gitlab addresses.
 219   ```
 220   git config --global user.name Your Name
 221   git config --global user.email your@email
 222   ```