Coding Guidelines

Intro

These guidelines are here to help write clean, safe, reliable code. Following them will also ensure you don't get torn apart during a code review, and will save your team leads' sanity.

Header Files

Think of header files as the user-facing interface to your API. Therefore, try to only include or declare items in the header file that will be of use outside the context of the .c file.

Functions that will be called all over the place: put in header

Functions that are only used internally: don't put in header

---

Global Variables

Global variables must be declared in the header file using the keyword extern. In the .c file, define or initialize the variable. More info: https://www.cprogramming.com/declare_vs_define.html

To access the variable, simply include the header file with the extern declaration, and refer to the variable by name like usual.

If you don't do this, you may get multiple definition errors or create multiple copies of the same variable.

Header: test.h

extern uint32_t foo;

C file: test.c

uint32_t foo = 234;

Globals should be initialized in an init() function, or they may be initialized at the top of the .c file.

---

Built-in Types

Use the types that have the bit size in the type name. These can be included with #include 'sys_common.h'.

It's important to use these because the bit size is important in embedded systems. It makes you think about what you're doing and how much memory you actually need. It also helps prevent errors because you will always know the size you're dealing with since it's not obfuscated.

Good:

#include `sys_common.h`
uint32_t foo;
int16_t bar;

Bad and horrible:

int foo;
short bar;