c-code-style: Instructions file for Codex

Agent instructions

This repository defines a C coding style. If you (an AI coding agent) are writing, editing, or reviewing .c/.h files in a project that adopts this style guide, follow this file.

Source of truth

Read CODING_RULES.md before writing code — it is the authoritative, complete rule set. Do not assume "typical" C conventions; several rules here are deliberately non-default (e.g. (void) required on zero-parameter functions, at most 2 return points per function, stdbool.h avoided, 3-character minimum name length). template.c and template.h are worked, clang-format-verified reference examples — match their formatting and doxygen alignment exactly.

What the formatter fixes for you

clang-format (this repo ships .clang-format) handles indentation, spacing, brace placement, pointer-asterisk alignment, function-prototype alignment, and trailing commas in struct initializers. Don't hand-format these — write reasonably and run the formatter afterward (see below).

What you must apply yourself while writing

A formatter cannot infer these; apply them as you write, not after:

• Names (variables, parameters, struct/enum members): lowercase, underscore word-separated, at least 3 characters. No __/_ prefix (reserved). static module-private functions get a prv_ prefix.
• stdint.h types except char/float/double; avoid stdbool.h (use 1/0).
• Don't rely on static initializers for global/static variables needing a real startup value in embedded contexts — add a module init() function.
• All locals declared at the top of a block, grouped by type, ordered: structs/enums (and pointers) → integers (widest unsigned first) → floating point.
• const-correct pointers/parameters; generic pointers are void*, cast internally, never cast away a void* return value.
• Every zero-parameter function uses (void), never empty ().
• At most 2 return points per function: one early return for parameter/argument validation, one at the end. No return in the middle — use a return-value variable instead.
• Check pointers against NULL before dereferencing (unless provably non-NULL by construction). Set a pointer to NULL immediately after free().
• Boolean-treated variables: if (x) / if (!x), never == 1/== 0. Counter/value variables: > 0 / == 0, never bare if (x).
• Doxygen on every function (including static): \brief, \param[in] / \param[out] per parameter, \return if non-void. Written at the function's definition (the .c file body), never duplicated at the header declaration. Description text aligned to column 22 (match template.c). Backtick any identifier/constant/literal in prose.