Source: https://github.com/MaJerle/c-code-style

Recommended C style and coding rules

This document describes C code style used by Tilen MAJERLE in his projects and libraries.

General rules
Comments
Functions
Variables
Compound statements
- Switch statement

General rules

Here are listed most obvious and important general rules. Please check them carefully before you continue with other chapters.

Use C99 standard
Do not use tabs, use spaces instead
Use 4 spaces per indent level
Use 1 space between keyword and opening bracket

/* OK */
if (condition)
while (condition)
for (init; condition; step)
do {} while (condition)

/* Wrong */
if(condition)
while(condition)
for(init;condition;step)
do {} while(condition)

Do not use space between function name and opening bracket

int32_t a = sum(4, 3);              /* OK */
int32_t a = sum (4, 3);             /* Wrong */

Never use __ or _ prefix for variables/functions/macros/types. This is reserved for C language itself
- Prefer prv_ name prefix for strictly module-private functions
Use only lowercase characters for variables/functions/macros/types with optional underscore _ char
Opening curly bracket is always at the same line as keyword (for, while, do, switch, if, ...)

size_t i;
for (i = 0; i < 5; ++i) {           /* OK */
}
for (i = 0; i < 5; ++i){            /* Wrong */
}
for (i = 0; i < 5; ++i)             /* Wrong */
{
}

Use single space before and after comparison and assignment operators

int32_t a;
a = 3 + 4;              /* OK */
for (a = 0; a < 5; ++a) /* OK */
a=3+4;                  /* Wrong */
a = 3+4;                /* Wrong */
for (a=0;a<5;++a)       /* Wrong */

Use single space after every comma

func_name(5, 4);        /* OK */
func_name(4,3);         /* Wrong */

Do not initialize static and global variables to 0 (or NULL), let compiler do it for you

static int32_t a;       /* OK */
static int32_t b = 4;   /* OK */
static int32_t a = 0;   /* Wrong */

void
my_func(void) {
    static int32_t* ptr;/* OK */
    static char abc = 0;/* Wrong */
}

Declare all local variables of the same type in the same line

void
my_func(void) {
    char a;             /* OK */
    char a, b;          /* OK */
    char b;             /* Wrong, variable with char type already exists */
}

Declare local variables in order
1. Custom structures and enumerations
2. Integer types, wider unsigned type first
3. Single/Double floating point

int
my_func(void) {
    /* 1 */
    my_struct_t my;     /* First custom structures */
    my_struct_ptr_t* p; /* Pointers too */

    /* 2 */
    uint32_t a;
    int32_t b;
    uint16_t c;
    int16_t g;
    char h;
    /* ... */

    /* 3 */
    double d;
    float f;
}

Always declare local variables at the beginning of the block, before first executable statement
Declare counter variables in for loop

/* OK */
for (size_t i = 0; i < 10; ++i)

/* OK, if you need counter variable later */
size_t i;
for (i = 0; i < 10; ++i) {
    if (...) {
        break;
    }
}
if (i == 10) {

}

/* Wrong */
size_t i;
for (i = 0; i < 10; ++i) ...

Avoid variable assignment with function call in declaration, except for single variables

void
a(void) {
    /* Avoid function calls when declaring variable */
    int32_t a, b = sum(1, 2);

    /* Use this */
    int32_t a, b;
    b = sum(1, 2);

    /* This is ok */
    uint8_t a = 3, b = 4;
}

Except char, float or double, always use types declared in stdint.h library, eg. uint8_t for unsigned 8-bit, etc.
Do not use stdbool.h library. Use 1 or 0 for true or false respectively

/* OK */
uint8_t status;
status = 0;

/* Wrong */
#include <stdbool.h>
bool status = true;

Never compare against true, eg. if (check_func() == 1), use if (check_func()) { ... }
Always compare pointers against NULL value

void* ptr;

/* ... */

/* OK, compare against NULL */
if (ptr == NULL || ptr != NULL) {

}

/* Wrong */
if (ptr || !ptr) {

}

Always use pre-increment (and decrement respectively) instead of post-increment (and decrement respectively)

int32_t a = 0;
...

a++;            /* Wrong */
++a;            /* OK */

for (size_t j = 0; j < 10; ++j) {}  /* OK */

Always use size_t for length or size variables
Always use const for pointer if function should not modify memory pointed to by pointer
Always use const for function parameter or variable, if it should not be modified

/* When d could be modified, data pointed to by d could not be modified */
void
my_func(const void* d) {

}

/* When d and data pointed to by d both could not be modified */
void
my_func(const void* const d) {

}

/* Not required, it is advised */
void
my_func(const size_t len) {

}

/* When d should not be modified inside function, only data pointed to by d could be modified */
void
my_func(void* const d) {

}

When function may accept pointer of any type, always use void *, do not use uint8_t *
- Function must take care of proper casting in implementation

/*
 * To send data, function should not modify memory pointed to by `data` variable
 * thus `const` keyword is important
 *
 * To send generic data (or to write them to file)
 * any type may be passed for data,
 * thus use `void *`
 */
/* OK example */
void
send_data(const void* data, size_t len) { /* OK */
    /* Do not cast `void *` or `const void *` */
    const uint8_t* d = data;/* Function handles proper type for internal usage */
}

void
send_data(const void* data, int len) {    /* Wrong, not not use int */
}

Always use brackets with sizeof operator
Never use Variable Length Array (VLA). Use dynamic memory allocation instead with standard C malloc and free functions or if library/project provides custom memory allocation, use its implementation
- Take a look at LwMEM, custom memory management library

/* OK */
#include <stdlib.h>
void
my_func(size_t size) {
    int32_t* arr;
    arr = malloc(sizeof(*arr) * n); /* OK, Allocate memory */
    arr = malloc(sizeof *arr * n);  /* Wrong, brackets for sizeof operator are missing */
    if (arr == NULL) {
        /* FAIL, no memory */
    }

    free(arr);  /* Free memory after usage */
}

/* Wrong */
void
my_func(size_t size) {
    int32_t arr[size];  /* Wrong, do not use VLA */
}

Always compare variable against zero, except if it is treated as boolean type
Never compare boolean-treated variables against zero or one. Use NOT (!) instead

size_t length = 5;  /* Counter variable */
uint8_t is_ok = 0;  /* Boolean-treated variable */
if (length)         /* Wrong, length is not treated as boolean */
if (length > 0)     /* OK, length is treated as counter variable containing multi values, not only 0 or 1 */
if (length == 0)    /* OK, length is treated as counter variable containing multi values, not only 0 or 1 */

if (is_ok)          /* OK, variable is treated as boolean */
if (!is_ok)         /* OK, -||- */
if (is_ok == 1)     /* Wrong, never compare boolean variable against 1! */
if (is_ok == 0)     /* Wrong, use ! for negative check */

Always use /* comment */ for comments, even for single-line comment
Always include check for C++ with extern keyword in header file
Every function must include doxygen-enabled comment, even if function is static
Use English names/text for functions, variables, comments
Use lowercase characters for variables
Use underscore if variable contains multiple names, eg. force_redraw. Do not use forceRedraw
Never cast function returning void *, eg. uint8_t* ptr = (uint8_t *)func_returning_void_ptr(); as void * is safely promoted to any other pointer type
- Use uint8_t* ptr = func_returning_void_ptr(); instead
Always use < and > for C Standard Library include files, eg. #include <stdlib.h>
Always use "" for custom libraries, eg. #include "my_library.h"
When casting to pointer type, always align asterisk to type, eg. uint8_t* t = (uint8_t*)var_width_diff_type
Always respect code style already used in project or library

Comments

Comments starting with // are not allowed. Always use /* comment */, even for single-line comment

//This is comment (wrong)
/* This is comment (ok) */

For multi-line comments use space+asterisk for every line

/*
 * This is multi-line comments,
 * written in 2 lines (ok)
 */

/**
 * Wrong, use double-asterisk only for doxygen documentation
 */

/*
* Single line comment without space before asterisk (wrong)
*/

/*
 * Single line comment in multi-line configuration (wrong)
 */

/* Single line comment (ok) */

Use 12 indents (12 * 4 spaces) offset when commenting. If statement is larger than 12 indents, make comment 4-spaces aligned (examples below) to next available indent

void
my_func(void) {
    char a, b;

    a = call_func_returning_char_a(a);          /* This is comment with 12*4 spaces indent from beginning of line */
    b = call_func_returning_char_a_but_func_name_is_very_long(a);   /* This is comment, aligned to 4-spaces indent */
}

Functions

Every function which may have access from outside its module, must include function prototype (or declaration)
Function name must be lowercase, optionally separated with underscore _ character

/* OK */
void my_func(void);
void myfunc(void);

/* Wrong */
void MYFunc(void);
void myFunc();

When function returns pointer, align asterisk to return type

/* OK */
const char* my_func(void);
my_struct_t* my_func(int32_t a, int32_t b);

/* Wrong */
const char *my_func(void);
my_struct_t * my_func(void);

Align all function prototypes (with the same/similar functionality) for better readability

/* OK, function names aligned */
void        set(int32_t a);
my_type_t   get(void);
my_ptr_t*   get_ptr(void);

/* Wrong */
void set(int32_t a);
const char * get(void);

Function implementation must include return type and optional other keywords in separate line

/* OK */
int32_t
foo(void) {
    return 0;
}

/* OK */
static const char*
get_string(void) {
    return "Hello world!\r\n";
}

/* Wrong */
int32_t foo(void) {
    return 0;
}

Variables

Make variable name all lowercase with optional underscore _ character

/* OK */
int32_t a;
int32_t my_var;
int32_t myvar;

/* Wrong */
int32_t A;
int32_t myVar;
int32_t MYVar;

Group local variables together by type

void
foo(void) {
    int32_t a, b;   /* OK */
    char a;
    char b;         /* Wrong, char type already exists */
}

Do not declare variable after first executable statement

void
foo(void) {
    int32_t a;
    a = bar();
    int32_t b;      /* Wrong, there is already executable statement */
}

You may declare new variables inside next indent level

int32_t a, b;
a = foo();
if (a) {
    int32_t c, d;   /* OK, c and d are in if-statement scope */
    c = foo();
    int32_t e;      /* Wrong, there was already executable statement inside block */
}

Declare pointer variables with asterisk aligned to type

/* OK */
char* a;

/* Wrong */
char *a;
char * a;

When declaring multiple pointer variables, you may declare them with asterisk aligned to variable name

/* OK */
char *p, *n;

Compound statements

Every compound statement must include opening and closing curly bracket, even if it includes only 1 nested statement
Every compound statement must include single indent; when nesting statements, include 1 indent size for each nest

/* OK */
if (c) {
    do_a();
} else {
    do_b();
}

/* Wrong */
if (c)
    do_a();
else
    do_b();

/* Wrong */
if (c) do_a();
else do_b();

In case of if or if-else-if statement, else must be in the same line as closing bracket of first statement

/* OK */
if (a) {

} else if (b) {

} else {

}

/* Wrong */
if (a) {

}
else {

}

/* Wrong */
if (a) {

}
else
{

}

In case of do-while statement, while part must be in the same line as closing bracket of do part

/* OK */
do {
    int32_t a;
    a = do_a();
    do_b(a);
} while (check());

/* Wrong */
do
{
/* ... */
} while (check());

/* Wrong */
do {
/* ... */
}
while (check());

Indentation is required for every opening bracket

if (a) {
    do_a();
} else {
    do_b();
    if (c) {
        do_c();
    }
}

Never do compound statement without curly bracket, even in case of single statement. Examples below show bad practices

if (a) do_b();
else do_c();

if (a) do_a(); else do_b();

Empty while, do-while or for loops must include brackets

/* OK */
while (is_register_bit_set()) {}

/* Wrong */
while (is_register_bit_set());
while (is_register_bit_set()) { }
while (is_register_bit_set()) {
}

If while (or for, do-while, etc) is empty (it can be the case in embedded programming), use empty single-line brackets

/* Wait for bit to be set in embedded hardware unit
uint32_t* addr = HW_PERIPH_REGISTER_ADDR;

/* Wait bit 13 to be ready */
while (*addr & (1 << 13)) {}        /* OK, empty loop contains no spaces inside curly brackets */
while (*addr & (1 << 13)) { }       /* Wrong */
while (*addr & (1 << 13)) {         /* Wrong */

}
while (*addr & (1 << 13));          /* Wrong, curly brackets are missing. Can lead to compiler warnings or unintentional bugs */

Always prefer using loops in this order: for, do-while, while
Avoid incrementing variables inside loop block if possible, see examples

/* Not recommended */
int32_t a = 0;
while (a < 10) {
    .
    ..
    ...
    ++a;
}

/* Better */
for (size_t a = 0; a < 10; ++a) {

}

/* Better, if inc may not happen in every cycle */
for (size_t a = 0; a < 10; ) {
    if (...) {
        ++a;
    }
}

Switch statement

Add single indent for every case statement
Use additional single indent for break statement in each case or default

/* OK, every case has single indent */
/* OK, every break has additional indent */
switch (check()) {
    case 0:
        do_a();
        break;
    case 1:
        do_b();
        break;
    default:
        break;
}

/* Wrong, case indent missing */
switch (check()) {
case 0:
    do_a();
    break;
case 1:
    do_b();
    break;
default:
    break;
}

/* Wrong */
switch (check()) {
    case 0:
        do_a();
    break;      /* Wrong, break must have indent as it is under case */
    case 1:
    do_b();     /* Wrong, indent under case is missing */
    break;
    default:
        break;
}

Always include default statement

/* OK */
switch (var) {
    case 0:
        do_job();
        break;
    default:
        break;
}

/* Wrong, default is missing */
switch (var) {
    case 0:
        do_job();
        break;
}

If local variables are required, use curly brackets and put break statement inside.
- Put opening curly bracket in the same line as case statement

switch (a) {
    /* OK */
    case 0: {
        int32_t a, b;
        char c;
        a = 5;
        /* ... */
        break;
    }

    /* Wrong */
    case 1:
    {
        int32_t a;
        break;
    }

    /* Wrong, break shall be inside */
    case 2: {
        int32_t a;
    }
    break;
}

AmirHosein-Gharaati/c-code-style.md

Select an option

No results found