C Code Style

C code style

This skill applies whenever you are writing, editing, or reviewing .c or .h files in a project that adopts this style guide. The full rule set lives in CODING_RULES.md at the repository root — that file is the single source of truth (this repository's README.md is just a symlink to it, so it renders on the GitHub front page). This skill exists to make the rules operational: what to self-apply while writing code, and how to run the formatter afterward.

1. Read the rules first

Before writing or editing C code, read CODING_RULES.md in this repository (or wherever this skill was installed alongside it — if it's not there, the checklist in step 3 below is a self-contained fallback). Do not rely on memory of "typical" C style — several of this guide's rules are deliberately non-default (e.g. (void) on zero-parameter functions, at most 2 return points per function, no stdbool.h).

2. What clang-format fixes for you

Don't hand-format these — write reasonably and let the formatter normalize them in step 4: indentation and spacing, brace placement, pointer-asterisk alignment, function-prototype alignment, trailing commas in struct initializers, blank-line and parenthesis spacing.

3. What clang-format will NOT fix — apply these yourself while writing

These are semantic or naming rules; a formatter cannot infer them. Apply them as you write, not after:

• Names (variables, parameters, struct/enum members) are lowercase with underscores and at least 3 characters. Never a bare __/_ prefix. static module-private functions use a prv_ prefix.
• Use stdint.h types (uint8_t, int32_t, ...) except char/float/double. Avoid stdbool.h; use 1/0.
• Don't rely on static initializers for global/static variables that need a real startup value in embedded contexts — give the module an init() function instead.
• Declare all locals at the top of a block, grouped by type, in order: custom structs/enums (and their pointers) → integers (widest unsigned first) → floating point.
• const-correct pointers and parameters; generic pointers are void*, cast internally, never cast a void* return value.
• Every function with zero parameters uses (void), never empty ().
• A function has at most 2 return points: one early return for parameter/argument validation, one at the end. No return in the middle — use a return-value variable to accumulate the result instead.
• Check a pointer against NULL before dereferencing it (unless the surrounding code guarantees it can't be NULL). After free(ptr), immediately set ptr = NULL.
• Boolean-treated variables are compared with if (x) / if (!x), never == 1 / == 0; counter/value variables use > 0 / == 0, never bare if (x).
• Doxygen: every function (including static ones) gets a \brief, a \param[in]/\param[out] per parameter, and a \return if it returns non-void. The doc block goes at the function's definition (where the body is, typically the .c file) — never duplicated at the declaration in the header. Pad tags so description text starts at column 22 (see template.c/template.h for the exact alignment). Wrap identifiers, constants, and literals referenced in prose in backticks.