Include guards

#pragma once

#ifndef MODULE_H
#define MODULE_H
...
#endif

Although #pragma once isn't officially part of the C standard, it's widely supported and easier to use than include guards.

Note that include guards are used to prevent double inclusion of headers.

Conditionals and loops

if (cond) {
  ...
} else if (cond) {
  ...
} else {
  ...
}

OR

for (int i = 0; i < x; i++) {
  ...
}

if(cond)
{
}
else
{
}

OR

if (cond)
  func();

OR

if(cond){
  ...
}

Braces are always required, even for single-line statements. They should be on the same line as the conditional.

Adequate spacing should be provided between statements.

In general, please be consistent.

Prefer descriptive, reasonable length variable names.

Note that function and variable names follow the underscore_lowercase naming convention.

Variable names

(static)

static uint8_t s_descriptive_name = 0;

static void prv_func(void) {
  // do stuff
}

A static variable that is global to a file should be prefixed with s_.

You should not have static variables in a function, since your functions should not be maintaining state (unless you have a really good reason).

Function names

(public)

Function names

(private)

Macros

#define MODULE_MACRO(x) ((x)*2)

Avoid macros as functions, but they should be ALL_CAPS and their parameters should be enclosed in brackets if used.

Macros should also be prefixed with the module's name.

Enums

typedef enum {
  MODULE_ENUM_TYPE_A = 0,
  MODULE_ENUM_TYPE_B,
  MODULE_ENUM_TYPE_C,
NUM_MODULE_ENUM_TYPES,
} ModuleEnumType;

enum enum_type {
  a,
  b,
  c,
};

typedef enum {
  TYPE_FOO = 0,
  TYPE_BAR
} ModuleEnumType;

Typedef enums because we generally use them to group bitmasks, and it would get messy quickly.

Like all types and functions, enums should be prefixed with their module name. This goes for both the typedef and actual enum names.

Declare them in ALL_CAPS prefixed with the enum name. The first entry should have an initial value (usually 0). The final entry in any enum should be NUM_MODULE_ENUM_TYPES. Note the plurality of the type and the prefix NUM_. This allows for the writing of nice guard clauses.

typedef struct ModuleFoo {
  ...
} ModuleFoo;

struct Foo {
  ...
};

Use UpperCamelCase for struct definitions.

Typedef'd structs make it easier to think about them as objects, and provide some abstraction.

The original struct should still be named to allow for forward declarations.

Structs should also be prefixed with the module name.

GPIOAddress address = { 1, 0 };
int a[] = { 0, 1, 2, 3 };

// GNU Style
GPIOAddress addresses[] = {
  [GPIO_PIN1] = { .port = 1, .pin = 1 }, //
  [GPIO_PIN2] = { .port = 1, .pin = 2 }, //
};

GPIOAddress address = {1, 0};
int a[] = {0, 1, 2, 3};

Structs and arrays should have 1 space between each brace and the first/last elements.

GNU Style designated initializers are encouraged as they are more explicit and ensure consistency in the result of changes in definitions of structs/enums.

The trailing // is used to help clang-format align the elements as a single column as opposed to bin-packing.

As of August 2017 there is a bug in clang-format so that

{.port = 1, .pin = 1 } is the result of formatting this has been fixed upstream and should be resolved in the next release.

Make use of bitwise operations whenever working with bitmasks.

Use macro or enums to define bitmasks.

Try to keep the order of operations from MSB to LSB.

// This is a well-formatted comment.

// |a| does foo.

int8_t a = 0;  // This is also ok.

Use the // syntax for comments.

Comments can also be trailing to a line.

Comments width should be 100, avoid putting unnecessary line breaks as it makes comments hard to read.

When referencing a variable within a comment it is preferred to surround it with |variable|.

int *pointer = NULL;
void func(int *x, int *y);

int* pointer = NULL;
int * x = NULL;
int *x, y;
void func(int * x, int* y);

The asterisk should always be adjacent to the variable.

Do not declare multiple variables in the same declaration if any are pointers.

#pragma once
// Module Summary (short)
// Requires ... to be initialized
//
// Module description - intent, intended usage, etc.
#include ...

typedef ...

// Function purpose and specific parameter details
void module_foo(void);

We state any modules that must be initialized before the module can be used.

The module description should explain the intent behind the module, its expected usage, and any contracts or side-effects (ex. event data, interrupts, etc). Do not explain how your module works internally (that can go in the source file if necessary).

Finally, keep function comments short. Be sure to state any bounds or expectations for parameters, such as requiring persistance.

// Memory of *Storage must persist. 
typedef struct *Storage {
  // ...
} *Storage;

// Memory of *Settings can be ethereal

typedef struct *Settings {
  // ...
} *Ssettings;

if (val == NULL)

or

if (val != NULL)

if (!val)

or

if (val)

while (true) {
   while(event_process(&e) == STATUS_CODE_OK) {
        // Events to process
   }
}

For consistency.

// First the header you're implementing or testing
// (if applicable)
#include "my_modules_header.h"

// Then C standard library headers alphabetically
#include <stdbool.h>
#include <stdint.h>

// Then all other headers sorted alphabetically
#include "gpio.h"
#include "log.h"
#include "my_other_project_header.h"
#include "some_library_header.h"

Put your includes into three sections separated by blank lines. The first is for the header of the module you're implementing or testing, if applicable. Then, place C standard library headers in angle brackets, sorted alphabetically. Finally, place all other library and project headers, sorted alphabetically.

This format makes it easy to see what headers have been included.