A teammate lowers a function's cognitive complexity from 24 to 8 by extracting six private helpers. How do you judge whether the code actually got easier to read?

## Why the question arises Cognitive complexity, cyclomatic complexity and most linter thresholds are computed **per function**. Extracting code into another function therefore *always* reduces the parent's score, and often reduces the aggregate too, because the nesting penalty is charged from zero again inside each helper. That makes the metric trivially gameable: it measures a local property while comprehension is a global one. This is a textbook instance of **Goodhart's law** — when a measure becomes a target, it stops being a good measure. ## Extraction that genuinely helps: chunking Human working memory holds only a handful of live facts. Extraction helps when the helper's **name replaces its body** in the reader's head — one remembered concept instead of ten remembered statements. Conditions for that: 1. **The name is a true abstraction** in the domain's vocabulary (`isEligibleForRefund`, `applyLoyaltyDiscount`), not a positional label (`part2`, `helper`, `processData`). 2. **The interface is narrow.** Few parameters, one return value. A helper needing six arguments means you cut across a cohesive computation and the caller's context travels with the call. 3. **Effects are explicit.** A helper that quietly mutates caller state, or that reads/writes new mutable fields added just to pass data, replaces local variables with object state — a strictly wider scope and harder to reason about. 4. **It is independently meaningful.** You could name it in a design conversation, test it alone, and plausibly reuse it. Single-use is fine if the concept is real. 5. **Cohesion, not just size.** The split follows a seam in the logic (validate / compute / persist), not an arbitrary line count. ## Extraction that hurts - **Shotgun/yo-yo reading.** Understanding the whole now requires jumping through six definitions. Each jump is a context switch and leaves an unresolved item in working memory. The parent got shorter; total effort went up. - **Temporal coupling made invisible.** If the helpers must be called in a specific order, and that order is enforced only by the parent's line sequence plus shared fields, the extraction has hidden a real constraint. - **False reuse pressure.** A helper created for one caller invites a second caller with slightly different needs, which grows parameters and flags until it serves nobody well. - **Parameter/flag creep.** `applyRules(order, ctx, true, false, null)` is worse than the inline block it replaced. ## How to judge, concretely - **Read-aloud test:** read only the parent function. Can you state what it does and in what order, without opening a helper? If yes, the abstraction holds. - **Naming test:** could you have named each helper *before* writing it? Names that only made sense after the split usually describe position, not meaning. - **Parameter test:** count arguments and shared mutable fields. Growth means the seam was wrong. - **Diff-review test:** in review, does the change read like a design improvement independent of the linter? If the only justification is 'the rule was failing', that is the tell. - **Alternatives to consider instead:** guard clauses to flatten nesting (removes complexity rather than moving it); replacing a conditional chain with a lookup table or polymorphic dispatch; splitting the *type* rather than the function when the function is long because the class does too much. ## The mature position A high complexity score is a **reliable smell and an unreliable diagnosis**. Use it to trigger a look, then fix the underlying design — usually a function doing several jobs, a missing domain concept, or validation that belongs at a boundary. Judge the fix by human comprehension, in review; the score should improve as a *side effect*. Teams that invert this — treating the number as the goal — end up with codebases that pass every gate and still take a week to onboard into.