| 1 |
# OpenCryptoki coding style |
| 2 |
|
| 3 |
This document describes the preferred coding style for the OpenCryptoki project |
| 4 |
and its related projects (openssl-ibmca and openssl-ibmpkcs11). Coding style is |
| 5 |
always of personal taste, but defining one coding style makes the maintenance of |
| 6 |
the project easier and gives a standard face for the source code, something that |
| 7 |
this projects have been lacking for the past years. |
| 8 |
|
| 9 |
The inspiration and formatting of this document came from the Linux Kernel |
| 10 |
coding style document, but make no assumption as the coding style differ from |
| 11 |
each other on some aspects. |
| 12 |
|
| 13 |
## 0. Setting up automatic code style check |
| 14 |
|
| 15 |
To help developers on checking if their code changes are following the coding |
| 16 |
style format, we created a pre-commit git hook which is shared under .githooks/ |
| 17 |
directory. This hook will use GNU indent to check your code changes. |
| 18 |
|
| 19 |
You might wonder "why we ask for user confirmation?". Well, we don't want to |
| 20 |
create a overhead for developers that are working on feature branches and their |
| 21 |
code changes are not yet ready for a pull request. |
| 22 |
|
| 23 |
To set up the pre-commit hook, each developer after cloning the project needs |
| 24 |
to run: |
| 25 |
$ ln -s ../../.githooks/pre-commit .git/hooks/pre-commit |
| 26 |
|
| 27 |
## 1. Indentation |
| 28 |
|
| 29 |
Tabs are 4 space characters, differently from many projects that define it as 8 |
| 30 |
characters. The main idea behind this is that 4 characters should give you a |
| 31 |
clear idea about where a block of control starts and ends. |
| 32 |
|
| 33 |
All conditional preprocessor definitions must be indented, along with the `#` token. |
| 34 |
|
| 35 |
e.g.: |
| 36 |
|
| 37 |
```c |
| 38 |
#ifdef DEF_A |
| 39 |
#define DEF_A1 |
| 40 |
#else |
| 41 |
#define DEF_B1 |
| 42 |
#endif |
| 43 |
``` |
| 44 |
|
| 45 |
## 2. Line length |
| 46 |
|
| 47 |
To keep the code readable and maintainable, the limit on the length of lines is |
| 48 |
80 columns and this is a strongly preferred limit. |
| 49 |
|
| 50 |
## 3. Placing Braces and Spaces |
| 51 |
|
| 52 |
Here we follow Kernighan and Ritchie teachings. An opening brace is put last on |
| 53 |
the line, and put the closing brace first, e.g.: |
| 54 |
|
| 55 |
```c |
| 56 |
if (x == 0) { |
| 57 |
do_y(); |
| 58 |
} |
| 59 |
``` |
| 60 |
|
| 61 |
This applies to all non-function statement blocks (if, switch, for, while, do). |
| 62 |
Another example: |
| 63 |
|
| 64 |
```c |
| 65 |
switch (value) { |
| 66 |
case 1: |
| 67 |
return "one"; |
| 68 |
case 2: |
| 69 |
return "two"; |
| 70 |
case 3: |
| 71 |
return "three"; |
| 72 |
default: |
| 73 |
return NULL; |
| 74 |
} |
| 75 |
``` |
| 76 |
|
| 77 |
However, there is one special case, functions: their opening brace stays at the |
| 78 |
beginning of the next line, e.g.: |
| 79 |
|
| 80 |
```c |
| 81 |
int func(int x) |
| 82 |
{ |
| 83 |
do_something(); |
| 84 |
} |
| 85 |
``` |
| 86 |
|
| 87 |
Follow other examples: |
| 88 |
|
| 89 |
```c |
| 90 |
do { |
| 91 |
do_something(); |
| 92 |
} while (condition); |
| 93 |
``` |
| 94 |
|
| 95 |
```c |
| 96 |
if (x == 1) { |
| 97 |
do_one(); |
| 98 |
} else if (x > 1) { |
| 99 |
do_two(); |
| 100 |
} else { |
| 101 |
do_three(); |
| 102 |
} |
| 103 |
``` |
| 104 |
|
| 105 |
It is not necessary to use braces when there is only a single statement, e.g.: |
| 106 |
|
| 107 |
```c |
| 108 |
if (x == 1) |
| 109 |
do_something(); |
| 110 |
``` |
| 111 |
|
| 112 |
and |
| 113 |
|
| 114 |
```c |
| 115 |
if (x == 1) |
| 116 |
do_something(); |
| 117 |
else |
| 118 |
do_something_else(); |
| 119 |
``` |
| 120 |
|
| 121 |
This does not apply when only one branch in a conditional statement is a single |
| 122 |
statement. In this, case use braces in all branches, e.g.: |
| 123 |
|
| 124 |
```c |
| 125 |
if (x == 1) { |
| 126 |
do_something(); |
| 127 |
do_something_more(); |
| 128 |
} else { |
| 129 |
do_something_else(); |
| 130 |
} |
| 131 |
``` |
| 132 |
|
| 133 |
### 3.1. Spaces |
| 134 |
|
| 135 |
Always use a space after these keywords: |
| 136 |
``` if, switch, case, for, do, while ``` |
| 137 |
|
| 138 |
E.g.: |
| 139 |
|
| 140 |
```c |
| 141 |
if (condition) { |
| 142 |
.. |
| 143 |
} |
| 144 |
``` |
| 145 |
|
| 146 |
The following keywords should not have a space between them and their |
| 147 |
parentheses: |
| 148 |
``` sizeof, typeof ``` |
| 149 |
|
| 150 |
E.g.: |
| 151 |
|
| 152 |
```c |
| 153 |
s = sizeof(struct alg); |
| 154 |
``` |
| 155 |
|
| 156 |
Do **not** add spaces around (inside) parenthesized expressions, e.g.: |
| 157 |
|
| 158 |
```c |
| 159 |
if ( x == 1 ) { |
| 160 |
.. |
| 161 |
} |
| 162 |
``` |
| 163 |
|
| 164 |
When declaring a pointer or a function that returns a pointer type, the ``*`` |
| 165 |
must be put adjacent to the data name or function name, e.g.: |
| 166 |
|
| 167 |
```c |
| 168 |
int *ptr; |
| 169 |
void ptrcopy(int *dest, char *src); |
| 170 |
int *get_address(int *ptr); |
| 171 |
``` |
| 172 |
|
| 173 |
Use one space on each side of the following operators: |
| 174 |
``` = + - < > * / % | & ^ <= >= == != ? : ``` |
| 175 |
|
| 176 |
but no space after unary operators: |
| 177 |
``` & * + - ~ ! ``` |
| 178 |
|
| 179 |
no space before postfix/after prefix increment and decrement operators: |
| 180 |
``` ++ -- ``` |
| 181 |
|
| 182 |
and no space around the ``.`` and ``->`` structure member operators. |
| 183 |
|
| 184 |
Do **not** leave trailing whitespace at the end of lines. |
| 185 |
|
| 186 |
## 4. Naming |
| 187 |
|
| 188 |
Avoid using CamelCase. It is preferred to name variables and functions by |
| 189 |
including an underscore between words, e.g.: |
| 190 |
|
| 191 |
```c |
| 192 |
int person_counter; |
| 193 |
``` |
| 194 |
|
| 195 |
## 5. Commenting |
| 196 |
|
| 197 |
Comments in the code make everyone's life easier, but don't be too verbose. |
| 198 |
Focus on **what** your function does and less on **how** it does. |
| 199 |
|
| 200 |
The preferred style for long multi-line comments is: |
| 201 |
|
| 202 |
```c |
| 203 |
/* |
| 204 |
* This is a multi-line comment. |
| 205 |
* |
| 206 |
* A column of asterisks on the left side, with beginning and ending |
| 207 |
* almost-blank lines. |
| 208 |
*/ |
| 209 |
``` |