Enhanced C Coding Style Cheat Sheet (Version 1.0)

Compact version of the Enhanced C Coding Style, extending the C Coding Style.

1. Scope

• The standard C Coding Style Cheat Sheet remains authoritative for general formatting, naming, line breaking, comments, and control flow.
• This cheat sheet covers only the enhanced C syntax additions.

2. File Prologue Macros

• Headers: #include "begin_header.h" → begin_header → declarations → end_header → #include "end_header.h".
• Implementations: #include "begin_impl.h" → begin_impl → definitions → end_impl.
• Do not include begin_common.h, end_common.h, begin_ptr.h, end_ptr.h, begin_integer.h, end_integer.h, begin_enum.h, end_enum.h, begin_cpp.h, or end_cpp.h directly in normal code.
• Inside the wrapper region, pointers are assumed nonnull unless marked otherwise.
• Pointer chains such as ** need explicit nullability per level. Prefer OutPtr...(...) for out parameters, otherwise use _opt / _req.

3. Type Inference Macros

• def name = expr; declares a const inferred local.
• set name = expr; declares a mutable inferred local.
• Prefer def unless mutation is required.
• Do not use inferred types where the resulting type would be unclear.

4. Guard and Early Exit Macros

• Prefer return_unless(...), continue_unless(...), and break_unless(...) over repeated assignment/check boilerplate.
• Use guard(...) { ... } endguard when a block should run only if assignments and an optional trailing condition succeed.
• Values bound by these macros are def locals.

5. Requirements and Assertions

• require(...): production requirement.
• requireFail(...): production failure shortcut for require(false, ...).
• assert(...): debug-only invariant.
• assertFail(...): debug-only failure shortcut for assert(false, ...).
• Prefer message variants when failure context matters.
• Do not use raw C library assert() in project code.

6. Integer Types

• Prefer project integer aliases over raw C integer types.
• Unsigned is the default: int8, int16, int32, int64.
• Signed types use a leading s: sint8, sint16, sint32, sint64.
• Exact-width types add e: int32e, sint32e.
• Minimum-width types add m: int32m, sint32m.
• Prefer fast types by default.
• Use exact-width types only where exact size is part of the contract.
• Prefer intCount for counts, sizes, offsets, and indices.

7. Enum and Option Macros

• Use defEnum( name, type ) for closed enums.
• Use defOpenEnum( name, type ) only when external extension is intended.
• Use defOptions( name, type ) or defClosedOptions( name, type ) for bitmask option sets.

8. Pointer and Nullability Macros

• Prefer Opt(type) for nullable values.
• Prefer OutPtr(type), OutPtrOpt(type), OptOutPtr(type), and OptOutPtrOpt(type) for out pointers.
• Use PtrArrayOf(type) and its optional variants for pointer arrays.
• Use _opt / _req directly when the wrapper forms cannot be used.
• _opt and _req attach to the pointer they follow: *_opt, not * _opt.
• _opt and _req stay closer to * than const: char *_opt const ptr.

9. Preprocessor Helper Macros

• Use STR(...) for stringification.
• Use CONCAT(...) for token concatenation.
• Use COUNT_ARGS(...) for variadic macro dispatch.

10. Other Helpers

• Use nothing for an explicit no-op where that reads better than (void)0.
• Use nil instead of NULL.
• Use static_assert(...) for compile-time checks.
• Use likely_true(...) and likely_false(...) only when justified.
• Prefer MIN, MAX, CLAMP, ROTL, ROTR, and HOST_TO_BE* / HOST_TO_LE* over local redefinitions.
• Use public only for symbols that really need default visibility.

11. Preference Rule

• When standard C and the project macro layer offer equivalent solutions, prefer the project layer.