Skip to content

S24.08: enforce top-down function ordering across all source files #423

Description

@DavidCozens

Parent epic: #254

Motivation

CLAUDE.md mandates a top-down function-ordering rule:

Within a source file, functions are ordered top-down so the reader sees
the lifecycle and public API first, then drills into helpers as they
appear: `_Create` first, `_Destroy` second, public functions after,
helper functions are forward-declared at the top of the file and
defined immediately beneath the function that first calls them.

In practice almost every E11 pool-class `Static.c` violates the
"defined immediately beneath their first caller" half of the rule —
`
_IndexFromHandle` / `*_CleanupAtIndex` (and similar pool helpers)
are grouped at the file end after `_Create` and `_Destroy`. This
came to light when CodeRabbit flagged `SolidSyslogPosixAddressStatic.c`
on PR #422 and the only honest defence was "matches every other
pool-class". I.e. the convention has drifted, not the new file.

This story tightens the whole tree to the documented rule in one pass.

Scope

All `.c` files under:

  • `Core/Source/` — every `Static.c` plus any `.c` that has helpers
    defined out of order
  • `Platform/{Posix,Windows,FreeRtos,Atomics,OpenSsl,MbedTls,FatFs}/Source/`
  • `Bdd/Targets/` C sources (best effort — these are Tier 3)

Tests (`Tests/`) out of scope — the test fixture grouping doesn't follow
the same rule.

Acceptance criteria

  • Every `*Static.c` pool-class file has `_Create` first, `_Destroy`
    second, then each helper immediately beneath its first caller
    (forward declarations at the top as needed).
  • Same for the non-Static.c production sources where helpers are
    currently grouped at file end (`SolidSyslog.c`, `SolidSyslogFormatter.c`,
    RecordStore.c`, etc. — audit on entry to the story).
  • No behaviour change. Diff is move-only.
  • CI green on all platforms.
  • Diff reviewed against the rule, not against existing precedent.

Out of scope

  • `Tests/` — fixture lifetime macros impose a different layout
  • Header files

Metadata

Metadata

Assignees

No one assigned

    Labels

    storyStory issue

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions