When to use

Use this skill when:

•writing new C code
•reviewing code for style compliance
•adding comments to existing code
•extracting magic numbers to constants
•normalizing coding patterns

Source of truth

•docs/CODE_STANDARDS.md — naming, comments, function size, ownership docs
•docs/SAFETY_RULESET.md — safety and determinism rules
•docs/LIBC_POLICY.md — allowed/forbidden libc functions

File header comments (required)

Every .c/.h file MUST start with:

/*
  path/to/file.c — Brief description (one line).

  Why: Explain the purpose and key design decisions.
*/

Function-level comments (when needed)

Add comments for:

•Complex algorithms (brief overview, not line-by-line)
•State machines (what each state variable tracks)
•Spec-derived logic (reference the spec, e.g., "UAX #29 GB11")
•Non-obvious defensive patterns (e.g., "accepts NULL for cleanup convenience")

Do NOT add comments that:

•Restate the code (/* increment i */ i++)
•Explain obvious stdlib usage
•Pad length without adding value

Strategic comment types

ASCII diagrams for data structures

/*
 * Ring buffer layout:
 *
 *   Case 1: tail >= head
 *     [....head=====tail....]
 *
 *   Case 2: tail < head (wrapped)
 *     [====tail......head====]
 */

Section markers in long functions

/* --- Validate inputs --- */
...
/* --- Process data --- */
...
/* --- Write outputs --- */

Format reminders for bit layouts

/* RGB stored as 0x00RRGGBB */

Invariant protection

/* Ensures offset + size doesn't overflow before pointer creation */

Named constants (required)

Extract magic numbers to named constants:

/* BAD */
if (align > 4096u) return false;

/* GOOD */
#define ZR_ARENA_MAX_ALIGN 4096u
if (align > ZR_ARENA_MAX_ALIGN) return false;

Group related constants with section comments:

/* --- SGR (Select Graphic Rendition) codes --- */
#define ZR_SGR_RESET     0u
#define ZR_SGR_BOLD      1u
#define ZR_SGR_ITALIC    3u

NULL check style

Use !ptr consistently:

/* GOOD */
if (!ptr) return ZR_ERR_INVALID_ARGUMENT;

/* AVOID */
if (ptr == NULL) return ZR_ERR_INVALID_ARGUMENT;

Function size

•Target: 20-40 lines
•Maximum: 50 lines
•If larger: split into helpers with clear names

Naming conventions

Type	Convention	Example
Functions	`module_action_noun()`	`arena_alloc_aligned()`
Variables	`snake_case` descriptive	`bytes_remaining`
Constants	`ZR_MODULE_NAME`	`ZR_DL_MAGIC`
Types	`zr_name_t`	`zr_arena_t`

Review checklist

Before finalizing code:

• File has header comment with "Why"
• Complex functions have brief overview comment
• Magic numbers extracted to named constants
• NULL checks use !ptr style
• Functions under 50 lines
• No comments that restate code