cognitive-refactor

Cognitive Refactor

A complexity score counts branches. A reader counts the places they must open to answer one question. Refactor to reduce the places. A change that lowers the score and raises the places is a regression.

Loops: split by stage, not by field

A loop that reads several facts from each item stays one loop. The shape of the result:

1. The function that owns the result owns the loop.
2. A helper takes one item, or one item and the running result, and returns the new result. widenServiceWindow(serviceWindow, row) is a rule. findEarliestDate(rows.map(...)) is a hidden loop.
3. When items must be checked before they are used, add one pass per stage: validate, then accumulate. Two passes by stage. One pass per field is the failure this section exists for.
4. Reach the complexity target by moving branches into per-item helpers. Moving the loop into helpers does not count.

// Wrong shape: one pass per field. A reader follows one row through six functions.
const billed = sumCents(rows.map((row) => row.billedAmount))
const paid = sumCents(rows.map((row) => row.paidAmount))
const serviceWindow = getServiceWindow(rows)
const claimNumbers = collectDistinct(rows.map((row) => row.claimNumber))

// Right shape: one pass to validate, one pass to accumulate, helpers per row.
const rowMissingMoney = rows.find(isMissingMoney)
if (rowMissingMoney) {
  return { ok: false, reason: "missing-money" }
}
let totals = EMPTY_TOTALS
let serviceWindow = EMPTY_WINDOW
const claimNumbers = new Set<string>()
for (const row of rows) {
  totals = addRowMoney(totals, row)
  serviceWindow = widenServiceWindow(serviceWindow, row)
  addIfPresent(claimNumbers, row.claimNumber)
}

Check: pick one item and count the functions a reader opens to learn what happens to it. The loop and the helpers it calls fit on one screen.

Loops: a built-in beats a hand-rolled accumulator

Before extracting a helper for a loop, check whether the loop only rebuilds a Map, Set, or grouping that a built-in already returns. When it does, delete the loop and the type that describes its shape. Keeping the helper does not make the code simpler. It adds one more place to open for a fact the language already tracks.