Debian Codegraph @

doc/coding_style.md

raw
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 ```