Versions Compared

Version Old Version 7 New Version 8
Changes made by

Karl Ding

Titus Chow

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

...


GoodNot GoodNotes

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.

Indentation2 space indentsAnything elseOnly use spaces. Do not use tabs. Use Unix-style line endings.
Variable namesuint8_t descriptive_name = 0;int a = 0;

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
}
Anything else

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)

void module_func(void);void func(void);Prefix public functions with the module's name.

Function names

(private)

static void prv_func(void);static void func(void);Prefix private functions with prv_ to denote that it is not visible.

Macros

#define MACRO(x) ((x)*2)
#define macro(x) x*2Avoid macros as functions, but they should be ALL_CAPS and their parameters should be enclosed in brackets if used.

Enums

typedef enum {
  ENUM_TYPE_A = 0,
  ENUM_TYPE_B,
  ENUM_TYPE_C,
} enum_type;
enum enum_type {
  a,
  b,
  c,
};

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

Declare them in ALL_CAPS prefixed with the enum name.

Datatypesuint8_t, uint16_t, int16_t, etc.char, int, short, etc.Use explicit standard datatypes.
Structs
typedef struct Foo {
  ...
} Foo;
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.

Struct/array initialization
GPIOAddress address = { 1, 0 };
int a[] = { 0, 1, 2, 3 };
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.
Line lengthsAround 100 charactersAbove 100 charactersTry to keep line lengths reasonable. Around 100 characters is a good length.
Bitwise operationsREG |= BIT1 | BIT2;REG |= BIT1 + BIT2;

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.

Comments// This is a well-formatted comment/* We do not use multi-line comments */Use the // syntax for comments.
Pointer formatting
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.