|
Packit |
8681c6 |
# OpenCryptoki coding style
|
|
Packit |
8681c6 |
|
|
Packit |
8681c6 |
This document describes the preferred coding style for the OpenCryptoki project
|
|
Packit |
8681c6 |
and its related projects (openssl-ibmca and openssl-ibmpkcs11). Coding style is
|
|
Packit |
8681c6 |
always of personal taste, but defining one coding style makes the maintenance of
|
|
Packit |
8681c6 |
the project easier and gives a standard face for the source code, something that
|
|
Packit |
8681c6 |
this projects have been lacking for the past years.
|
|
Packit |
8681c6 |
|
|
Packit |
8681c6 |
The inspiration and formatting of this document came from the Linux Kernel
|
|
Packit |
8681c6 |
coding style document, but make no assumption as the coding style differ from
|
|
Packit |
8681c6 |
each other on some aspects.
|
|
Packit |
8681c6 |
|
|
Packit |
8681c6 |
## 0. Setting up automatic code style check
|
|
Packit |
8681c6 |
|
|
Packit |
8681c6 |
To help developers on checking if their code changes are following the coding
|
|
Packit |
8681c6 |
style format, we created a pre-commit git hook which is shared under .githooks/
|
|
Packit |
8681c6 |
directory. This hook will use GNU indent to check your code changes.
|
|
Packit |
8681c6 |
|
|
Packit |
8681c6 |
You might wonder "why we ask for user confirmation?". Well, we don't want to
|
|
Packit |
8681c6 |
create a overhead for developers that are working on feature branches and their
|
|
Packit |
8681c6 |
code changes are not yet ready for a pull request.
|
|
Packit |
8681c6 |
|
|
Packit |
8681c6 |
To set up the pre-commit hook, each developer after cloning the project needs
|
|
Packit |
8681c6 |
to run:
|
|
Packit |
8681c6 |
$ ln -s ../../.githooks/pre-commit .git/hooks/pre-commit
|
|
Packit |
8681c6 |
|
|
Packit |
8681c6 |
## 1. Indentation
|
|
Packit |
8681c6 |
|
|
Packit |
8681c6 |
Tabs are 4 space characters, differently from many projects that define it as 8
|
|
Packit |
8681c6 |
characters. The main idea behind this is that 4 characters should give you a
|
|
Packit |
8681c6 |
clear idea about where a block of control starts and ends.
|
|
Packit |
8681c6 |
|
|
Packit |
8681c6 |
## 2. Line length
|
|
Packit |
8681c6 |
|
|
Packit |
8681c6 |
To keep the code readable and maintainable, the limit on the length of lines is
|
|
Packit |
8681c6 |
80 columns and this is a strongly preferred limit.
|
|
Packit |
8681c6 |
|
|
Packit |
8681c6 |
## 3. Placing Braces and Spaces
|
|
Packit |
8681c6 |
|
|
Packit |
8681c6 |
Here we follow Kernighan and Ritchie teachings. An opening brace is put last on
|
|
Packit |
8681c6 |
the line, and put the closing brace first, e.g.:
|
|
Packit |
8681c6 |
|
|
Packit |
8681c6 |
```
|
|
Packit |
8681c6 |
if (x == 0) {
|
|
Packit |
8681c6 |
do_y();
|
|
Packit |
8681c6 |
}
|
|
Packit |
8681c6 |
```
|
|
Packit |
8681c6 |
|
|
Packit |
8681c6 |
This applies to all non-function statement blocks (if, switch, for, while, do).
|
|
Packit |
8681c6 |
Another example:
|
|
Packit |
8681c6 |
|
|
Packit |
8681c6 |
```
|
|
Packit |
8681c6 |
switch (value) {
|
|
Packit |
8681c6 |
case 1:
|
|
Packit |
8681c6 |
return "one";
|
|
Packit |
8681c6 |
case 2:
|
|
Packit |
8681c6 |
return "two";
|
|
Packit |
8681c6 |
case 3:
|
|
Packit |
8681c6 |
return "three";
|
|
Packit |
8681c6 |
default:
|
|
Packit |
8681c6 |
return NULL;
|
|
Packit |
8681c6 |
}
|
|
Packit |
8681c6 |
```
|
|
Packit |
8681c6 |
|
|
Packit |
8681c6 |
However, there is one special case, functions: their opening brace stays at the
|
|
Packit |
8681c6 |
beginning of the next line, e.g.:
|
|
Packit |
8681c6 |
|
|
Packit |
8681c6 |
```
|
|
Packit |
8681c6 |
int func(int x)
|
|
Packit |
8681c6 |
{
|
|
Packit |
8681c6 |
do_something();
|
|
Packit |
8681c6 |
}
|
|
Packit |
8681c6 |
```
|
|
Packit |
8681c6 |
|
|
Packit |
8681c6 |
Follow other examples:
|
|
Packit |
8681c6 |
|
|
Packit |
8681c6 |
```
|
|
Packit |
8681c6 |
do {
|
|
Packit |
8681c6 |
do_something();
|
|
Packit |
8681c6 |
} while (condition);
|
|
Packit |
8681c6 |
```
|
|
Packit |
8681c6 |
|
|
Packit |
8681c6 |
```
|
|
Packit |
8681c6 |
if (x == 1) {
|
|
Packit |
8681c6 |
do_one();
|
|
Packit |
8681c6 |
} else if (x > 1) {
|
|
Packit |
8681c6 |
do_two();
|
|
Packit |
8681c6 |
} else {
|
|
Packit |
8681c6 |
do_three();
|
|
Packit |
8681c6 |
}
|
|
Packit |
8681c6 |
```
|
|
Packit |
8681c6 |
|
|
Packit |
8681c6 |
It is not necessary to use braces when there is only a single statement, e.g.:
|
|
Packit |
8681c6 |
|
|
Packit |
8681c6 |
```
|
|
Packit |
8681c6 |
if (x == 1)
|
|
Packit |
8681c6 |
do_something();
|
|
Packit |
8681c6 |
```
|
|
Packit |
8681c6 |
|
|
Packit |
8681c6 |
and
|
|
Packit |
8681c6 |
|
|
Packit |
8681c6 |
```
|
|
Packit |
8681c6 |
if (x == 1)
|
|
Packit |
8681c6 |
do_something();
|
|
Packit |
8681c6 |
else
|
|
Packit |
8681c6 |
do_something_else();
|
|
Packit |
8681c6 |
```
|
|
Packit |
8681c6 |
|
|
Packit |
8681c6 |
This does not apply when only one branch in a conditional statement is a single
|
|
Packit |
8681c6 |
statement. In this, case use braces in all branches, e.g.:
|
|
Packit |
8681c6 |
|
|
Packit |
8681c6 |
```
|
|
Packit |
8681c6 |
if (x == 1) {
|
|
Packit |
8681c6 |
do_something();
|
|
Packit |
8681c6 |
do_something_more();
|
|
Packit |
8681c6 |
} else {
|
|
Packit |
8681c6 |
do_something_else();
|
|
Packit |
8681c6 |
}
|
|
Packit |
8681c6 |
```
|
|
Packit |
8681c6 |
|
|
Packit |
8681c6 |
### 3.1. Spaces
|
|
Packit |
8681c6 |
|
|
Packit |
8681c6 |
Always use a space after these keywords:
|
|
Packit |
8681c6 |
``` if, switch, case, for, do, while ```
|
|
Packit |
8681c6 |
|
|
Packit |
8681c6 |
E.g.:
|
|
Packit |
8681c6 |
```
|
|
Packit |
8681c6 |
if (condition) {
|
|
Packit |
8681c6 |
..
|
|
Packit |
8681c6 |
}
|
|
Packit |
8681c6 |
```
|
|
Packit |
8681c6 |
|
|
Packit |
8681c6 |
The following keywords should not have a space between them and their
|
|
Packit |
8681c6 |
parentheses:
|
|
Packit |
8681c6 |
``` sizeof, typeof ```
|
|
Packit |
8681c6 |
|
|
Packit |
8681c6 |
E.g.:
|
|
Packit |
8681c6 |
```
|
|
Packit |
8681c6 |
s = sizeof(struct alg);
|
|
Packit |
8681c6 |
```
|
|
Packit |
8681c6 |
|
|
Packit |
8681c6 |
Do **not** add spaces around (inside) parenthesized expressions, e.g.:
|
|
Packit |
8681c6 |
```
|
|
Packit |
8681c6 |
if ( x == 1 ) {
|
|
Packit |
8681c6 |
..
|
|
Packit |
8681c6 |
}
|
|
Packit |
8681c6 |
```
|
|
Packit |
8681c6 |
|
|
Packit |
8681c6 |
When declaring a pointer or a function that returns a pointer type, the ``*``
|
|
Packit |
8681c6 |
must be put adjacent to the data name or function name, e.g.:
|
|
Packit |
8681c6 |
```
|
|
Packit |
8681c6 |
int *ptr;
|
|
Packit |
8681c6 |
void ptrcopy(int *dest, char *src);
|
|
Packit |
8681c6 |
int *get_address(int *ptr);
|
|
Packit |
8681c6 |
```
|
|
Packit |
8681c6 |
|
|
Packit |
8681c6 |
Use one space on each side of the following operators:
|
|
Packit |
8681c6 |
``` = + - < > * / % | & ^ <= >= == != ? : ```
|
|
Packit |
8681c6 |
|
|
Packit |
8681c6 |
but no space after unary operators:
|
|
Packit |
8681c6 |
``` & * + - ~ ! ```
|
|
Packit |
8681c6 |
|
|
Packit |
8681c6 |
no space before postfix/after prefix increment and decrement operators:
|
|
Packit |
8681c6 |
``` ++ -- ```
|
|
Packit |
8681c6 |
|
|
Packit |
8681c6 |
and no space around the ``.`` and ``->`` structure member operators.
|
|
Packit |
8681c6 |
|
|
Packit |
8681c6 |
Do **not** leave trailing whitespace at the end of lines.
|
|
Packit |
8681c6 |
|
|
Packit |
8681c6 |
## 4. Naming
|
|
Packit |
8681c6 |
|
|
Packit |
8681c6 |
Avoid using CamelCase. It is preferred to name variables and functions by
|
|
Packit |
8681c6 |
including an underscore between words, e.g.:
|
|
Packit |
8681c6 |
```
|
|
Packit |
8681c6 |
int person_counter;
|
|
Packit |
8681c6 |
```
|
|
Packit |
8681c6 |
|
|
Packit |
8681c6 |
## 5. Commenting
|
|
Packit |
8681c6 |
|
|
Packit |
8681c6 |
Comments in the code make everyone's life easier, but don't be too verbose.
|
|
Packit |
8681c6 |
Focus on **what** your function does and less on **how** it does.
|
|
Packit |
8681c6 |
|
|
Packit |
8681c6 |
The preferred style for long multi-line comments is:
|
|
Packit |
8681c6 |
|
|
Packit |
8681c6 |
```
|
|
Packit |
8681c6 |
/*
|
|
Packit |
8681c6 |
* This is a multi-line comment.
|
|
Packit |
8681c6 |
*
|
|
Packit |
8681c6 |
* A column of asterisks on the left side, with beginning and ending
|
|
Packit |
8681c6 |
* almost-blank lines.
|
|
Packit |
8681c6 |
*/
|
|
Packit |
8681c6 |
```
|
|
Packit |
8681c6 |
|