The 20% Rule for Codebases: A Practical Refactoring Playbook

A practical playbook to apply the 80/20 rule to code: intersect complexity with change to choose high‑leverage refactors and add simple guardrails.

Stephen Collins ·
hotspots refactoring complexity tech-debt ci

Most codebases obey a simple pattern: a small set of functions create a large share of the pain — incidents, slow reviews, fragile changes. That’s the 20% rule applied to code.

In practice, those functions sit at the intersection of two realities:

  1. They’re complex (lots of branching, deep nesting, many calls).
  2. They change often (recent churn, many touches, frequent rewrites).

The overlap — complex and volatile — is where you’ll get the most leverage.

A simple way to find your 20%

  • Make two short lists: the most changed functions/files in the last month, and the ones that are hardest to understand at a glance.
  • Intersect them. Don’t overthink the scoring; you’re looking for repeated offenders, not a perfect metric.
  • Pick 3 candidates you can actually change this week. Velocity beats perfection.

Case study (composite team story)

An API team kept firefighting the same endpoint. Reviews dragged, incidents popped up after “harmless” tweaks, and onboarding engineers avoided that area. They paused new work for half a day to map churn vs. complexity. One handler showed up everywhere: deep if/else, implicit coupling, and late‑stage validation.

They split the handler into three pure functions, pushed validation earlier, and added a small invariant check around the branching. Reviews sped up and post‑merge rollbacks dropped. Nothing fancy — just leverage on the right 20%.

The 60‑minute worksheet

  1. Pull change hotspots: list files/functions most touched in the last 30 days.
  2. Scan for complexity signals: deep nesting, long parameter lists, early returns, and broad fan‑out.
  3. Choose 3 targets: one “fire” (painful and active), one “debt” (painful but quiet), one “watch” (not painful yet, but trending).
  4. Define one action each: reduce branching, extract a sub‑function, isolate an external call behind an interface, or add a guard.
  5. Validate: re‑run your checks and capture before/after in the PR.

Common pitfalls

  • Chasing messy code that rarely changes — it won’t pay back soon.
  • Big‑bang rewrites — they stall, then rot. Prefer small, directed changes.
  • Optimizing the metric instead of the code — fewer branches isn’t a goal if readability drops.
  • No guardrails — refactors help once; policies keep the gains.

Keep it from creeping back

Whatever process you use, add a lightweight guardrail so new risks don’t slip in. If you want automation, tools like Hotspots compute a change‑aware risk score and can fail risky deltas in CI. Example:

hotspots analyze src/ --mode delta --policy

Whether you use a tool or a checklist, the principle holds: find the 20% that hurts the most, make it simpler, and protect it going forward.