57 lines
2.9 KiB
Markdown
57 lines
2.9 KiB
Markdown
---
|
|
name: control-flow-clarity
|
|
description: Branching and state-modeling clarity in C/C++. Use when writing or refactoring logic that branches on discrete values: if/else-if ladders, status flags, mode or state ints, or anything that should be an enum plus an exhaustive switch. Covers enum class over magic ints, exhaustive switch over nested if, early-return guard clauses, table dispatch, and when each is the right call.
|
|
---
|
|
|
|
# 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
|
|
|
|
- **Model a closed set of states/modes as an `enum class`, not ints or bools.**
|
|
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
|
|
|
|
- [ ] No int/bool standing in for a closed set of modes; it is an `enum class`.
|
|
- [ ] 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.
|