control-flow-clarity

---
name: control-flow-clarity
description: C/C++ state modeling and discrete-value dispatch. Use when introducing state/mode representations or refactoring branches on one discriminant.
---

# Control-Flow Clarity

The goal: a reviewer verifies correctness by reading, not by tracing. Branching
that mirrors the problem's shape is self-evident; branching that encodes it in
ad-hoc ints and nesting forces the reader to reconstruct intent.

## Core moves

- **Use `enum class` for multiple states/modes instead of numeric codes or combinations of flags.** Keep genuine boolean conditions as booleans.
  A variable kept honest by a comment ("0 = hidden, 1 = showing, 2 = confirm")
  is a latent bug. Make it an enum and the comment becomes the type.
- **Dispatch on an enum with an exhaustive `switch`, no `default`.** This
  codebase relies on it: omitting `default` lets the compiler flag the
  unhandled case when someone adds an enum value. A `default:` that swallows the
  unknown case throws that safety away. Add `default` only when "every other
  value does nothing" is a deliberate, documented decision.
- **Replace nested `if/else-if` ladders that branch on one discriminant with a
  `switch`.** If each branch only maps input to a value, prefer a lookup table
  (`static constexpr` array) over both.
- **Prefer early-return guard clauses over nested success bodies.** Handle the
  error/empty/skip cases first and return; keep the main path at the left
  margin.

## When NOT to switch

- Branches test unrelated conditions, not one discriminant: a guarded `if`
  sequence is honest; a switch would be forced.
- Two outcomes on a genuine boolean: keep the `if`.
- The discriminant is an open or unbounded set (arbitrary ints, strings): table
  or map, not a switch.

## Enum hygiene

- `enum class` by default for type safety. Plain `enum` only when values must
  implicitly convert (e.g. a value that doubles as a UI dropdown index), and
  then give it a trailing `_COUNT` sentinel for safe bounds/iteration, matching
  the existing settings enums.
- Name the discriminant after what it selects, not its storage:
  `Orientation orientation`, not `uint8_t mode`.
- No magic numeric codes for states. If you write a comment mapping numbers to
  meanings, you owe an enum.

## Self-review

- [ ] Multiple states/modes use an `enum class`; genuine boolean conditions stay booleans.
- [ ] Enum dispatch is an exhaustive `switch` with no catch-all `default` (or
      the `default` is a documented deliberate choice).
- [ ] No nested if/else-if ladder on a single discriminant that should be a
      switch or a table.
- [ ] Error/skip cases are early-return guards; the happy path is not buried.
- [ ] No magic numbers where a named enum or `constexpr` would state the intent.

More agent context in daveallie/crosspoint-reader

11 other files this repository gives its agents.

Also found in one other repository

The same file, byte for byte, in the weekly crawl of public GitHub.

• crosspoint-reader/crosspoint-reader8.4k