Skip to content

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

Closed

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
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    storyStory issue

    Type

    No type

    Projects

    No projects

      Milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions