In order to keep code consistent and easy for others to read, it is important that code is written using the same style and is properly commented. In short, we try following the Linux kernel coding style with some modification. We document the essentials below.
General
- Write code as a pair of
.h
and.c
files that go in their respective directory trees. Put definitions and the "external interface" in the header and code in the source. - Do not use doxygen. It makes it too easy to write useless documentation. Instead, have a look at "commenting" below and then "Documenting your code" to the left.
Indentation
Use tabs, not spaces. You should probably set the tab size to 4 or 8 in your editor if it is not set already. See the example under "Braces and spaces". Write switch-case like this:
int Translate (int value)
{
switch (value)
{
case 0:
return 4;
case 1:
return 99;
case 2:
return 159;
default:
return -1;
}
}
Line width
Try keeping the width of any line to a maximum of 80 characters.
Braces and spaces
- We differ from the kernel style here: always put both the opening and closing brace on separate lines. This makes them "align" with each other and is therefore easier to read.
- Do not use braces around a single statement. It makes the code 3 times as long.
- Exception to (1): You may put something on the same line as a closing brace in certain cases, such as a do-while loop.
Example:
int Foo (int bar)
{
if (bar)
return DoSomething (bar);
else
return -1;
}
Spaces
- Use a space after these:
if switch case for do while
. - Not whith these:
sizeof, typeof
etc. - No space padding inside parameter lists.
- Space between a function name and its arguments are recommended.
- The pointer star should be next to the name and not the type.
- Use spaces around:
= + - < > * / % | & ^ <= >= == != ? :
. - No spaces around decrement and increment:
-- ++
. - No spaecs arund
.
and->
structure and pointer operators. - DO NOT leave spaces on a blank line. Some editors do this, you can see them
with
git diff
before yougit commit
.
Naming
- It is okay to use short local names such as
tmp
andi
if you are careful. - Functions and definitions are in CamelCase and start with a capital letter. They should be descriptive, and if they are part of some form of "module" they should probably start with the name of the module. You may also use the kernel style if it makes sense. The kernel style is common in various core components, especially those that are to be POSIX compatible.
- Variables should be in camelCase, starting with a non-capital letter.
Functions
Avoid writing functions with more than 5-10 variables and that are longer than what you can fit on-screen at the same time. Using a 4K monitor in portrait mode is no excuse.
Commenting
Your comments should tell the WHAT and WHY, most likely not the HOW. Write a
multi-line comment using the /* ... */
style before the function body, and
use single-line comments //
inside. The style you should use is:
/*
* This is the preferred style for multi-line
* comments in the Linux kernel source code.
* Please use it consistently.
*
* Description: A column of asterisks on the left side,
* with beginning and ending almost-blank lines.
*/
Macros and definitions
Write macros and definitions in all upper-case. Use inline functions instead of large multiline macros.
Return values
Negative values for errors, zero for success and positive for normal things are recommended.
Higher level documentation
The "real" documentation should be written along with the code in markdown, so that both code and documentation are updated with each merge request. Eventually the new documentation will appear on the wiki at the same time as the code reaches the develop or master branch. Have a look at "Documenting your code" to the left for a how-to.