⁠Chapter 3. C Coding Guidelines

Table of Contents

⁠3.1. Style Guidelines

Pacemaker is a large, distributed project accepting contributions from developers with a wide range of skill levels and organizational affiliations, and maintained by multiple people over long periods of time. The guidelines in this section are not technically better than alternative approaches, but make project management easier.

Many of these simply ensure stylistic consistency, which makes reading, writing, and reviewing code easier.

⁠3.1.1. C Boilerplate

Every C file should start with a short copyright notice:

/*
 * Copyright <YYYY[-YYYY]> the Pacemaker project contributors
 *
 * The version control history for this file may have further details.
 *
 * This source code is licensed under <LICENSE> WITHOUT ANY WARRANTY.
 */

<LICENSE> should follow the policy set forth in the COPYING file, generally one of "GNU General Public License version 2 or later (GPLv2+)" or "GNU Lesser General Public License version 2.1 or later (LGPLv2.1+)".

Header files should additionally protect against multiple inclusion by defining a unique symbol.

#ifndef MY_HEADER_NAME__H
#  define MY_HEADER_NAME__H

// header code here

#endif // MY_HEADER_NAME__H

Public API header files should additionally declare "C" compatibility for inclusion by C++, and give a Doxygen file description. For example:

#ifdef __cplusplus
extern "C" {
#endif

/*!
 * \file
 * \brief My brief description here
 * \ingroup core
 */

// header code here

#ifdef __cplusplus
}
#endif

⁠3.1.2. Line Formatting

Indentation must be 4 spaces, no tabs.
Do not leave trailing whitespace.
Lines should be no longer than 80 characters unless limiting line length significantly impacts readability.

⁠3.1.3. Pointers

The * goes by the variable name, not the type:

char *foo;

Use a space before the * and after the closing parenthesis in a cast:

char *foo = (char *) bar;

⁠3.1.4. Function Definitions

In the function definition, put the return type on its own line, and place the opening brace by itself on a line.
For functions with enough arguments that they must break to the next line, align arguments with the first argument.
When a function argument is a function itself, use the pointer form.

static int
function_name(int bar, const char *a, const char *b,
              const char *c, void (*d)())
{

If a function name gets really long, start the arguments on their own line with 8 spaces of indentation:

static int
really_really_long_function_name_this_is_getting_silly_now(
        int bar, const char *a, const char *b,
        const char *c, const char *d)
{

⁠3.1.5. Control Statements (if, else, while, for, switch)

The keyword is followed by one space, then left parenthesis without space, condition, right parenthesis, space, opening bracket on the same line. else and else if are on the same line with the ending brace and opening brace, separated by a space.
Always use braces around control statement blocks, even if they only contain one line. This makes code review diffs smaller if a line gets added in the future, and avoids any chance of bad indenting making a line incorrectly appear to be part of the block.
Do not put assignments in if or while conditionals. This ensures that the developer’s intent is always clear, making code reviews easier and reducing the chance of using assignment where comparison is intended.

a = f();
if (a < 0) {
    statement1;
} else if (some_other_condition) {
    statement2;
} else {
    statement3;
}

In a switch statement, case is indented one level, and the body of each case is indented by another level. The opening brace is on the same line as switch.

switch (expression) {
    case 0:
        command1;
        break;
    case 1:
        command2;
        break;
    default:
        command3;
}

⁠3.1.6. Operators

Operators have spaces from both sides.
Do not rely on operator precedence; use parentheses when mixing operators with different priority.
No space is used after opening parenthesis and before closing parenthesis.

x = a + b - (c * d);