Technical debt — types, managing: Visual walkthrough

This is the visual companion to the parent note. We rebuild its central result — the repay rule — starting from nothing but "work takes time."

Step 1 — Draw the thing we are measuring: time per change

WHY start here? The parent note talks about "interest" and "principal" in dollars, but a dev team doesn't feel dollars — they feel days. If we measure in days, every symbol becomes something you can literally point at on a calendar. We pick time because it is the quantity that actually changes when code is messy.

PICTURE. Look at the figure. The left bar is the time to make one change if the code were clean. We give that height a name: $C_{0}$ (read "C-zero" — the cost of a change, in the 0-mess baseline case).

Step 2 — What a shortcut does: it makes the bar taller

WHY a fraction, not a fixed add-on? Because the slowdown scales with the work. A messy module makes a big change much worse and a tiny change a little worse — roughly in proportion. So we say the mess multiplies your time by "one whole clean amount, plus some fraction extra." That fraction is a new symbol:

PICTURE. The clean bar had height $C_{0}$ . The messy bar is that same $C_{0}$ plus an orange slice of height $C_{0} \times i$ stacked on top. Total messy height:

the real work C_{0} + extra dug-through-mess time = the interest C_{0} i = C_{0} (1 + i)

Term by term: $C_{0}$ is the work you'd always do; $C_{0} i$ is the penalty tax the mess adds; $(1 + i)$ is the whole stretched bar as a single factor.

Step 3 — One change is nothing. The pain is doing it again and again

WHY a new symbol $n$ ? Because the total waste depends entirely on how many times you come back. This is the single most important variable, and the parent note's whole ranking strategy ("fix hot code first") lives in it. We need to name it.

PICTURE. We line up $n$ copies of the messy bar. Each one carries its own orange "tax" slice. Stacking just the tax slices (ignore the clean part for a second) gives a tower of $n$ pieces, each of height $C_{0} i$ .

Step 4 — Add up all the tax: the total interest

WHY a sum ( $\sum$ )? The symbol $\sum$ just means "add these up." We use it because the total waste is nothing more than the same tax slice added once per visit — a repeated addition. Adding the same thing $n$ times is multiplication, which is why the sum collapses so cleanly:

Interest_{total} = k = 1 \sum n one tax slice C_{0} i = how many n \times each slice C_{0} i = n C_{0} i

Reading the $\sum$ : " $k = 1$ to $n$ " means do this once for each of the $n$ changes. Since every slice is the identical size $C_{0} i$ , adding $n$ of them is just $n \cdot C_{0} i$ .

PICTURE. The tower of orange slices from Step 3 fused into one tall orange block, labelled $n C_{0} i$ . That block is the total interest — the whole page hinges on its height.

Step 5 — The other option: pay it off once. Meet the principal $P$

WHY a single up-front cost? Because refactoring is a one-time job: you fix the mess, and the fix stays fixed. So it's not multiplied by $n$ — it's paid once. That deserves its own symbol.

PICTURE. Two side-by-side towers. Left ("carry the debt"): the tall orange interest block $n C_{0} i$ . Right ("pay the principal"): a single teal block of height $P$ , and then flat clean bars forever after.

Step 6 — Compare the two towers: the repay rule

WHY the base costs cancel (the algebra behind the picture). Write the full time each path costs across the $n$ future changes:

Carry the debt: every change is a messy bar $C_{0} (1 + i)$ , done $n$ times ⇒ $n C_{0} (1 + i) = n C_{0} + n C_{0} i$ .
Pay the principal first: one-time $P$ , then every change is a clean bar $C_{0}$ , done $n$ times ⇒ $P + n C_{0}$ .

We refactor when paying is cheaper:

pay then clean P + n C_{0} < carry the mess n C_{0} + n C_{0} i

Both sides carry the identical base term $n C_{0}$ — the real work you must do either way. Subtract $n C_{0}$ from both sides and it vanishes, leaving only the parts that actually differ:

P + n C_{0} < n C_{0} + n C_{0} i ⟹ P < n C_{0} i

That cancellation is the whole point: the base work $n C_{0}$ is unavoidable and doesn't help you decide, so it drops out — only the one-time fix $P$ versus the total interest $n C_{0} i$ remains.

The break-even case $P = n C_{0} i$ . When the two towers are exactly equal, both paths cost the same total time — you are indifferent: refactoring neither saves nor loses days. The scale sits perfectly level. Because a refactor also buys you cleaner, safer code (fewer future surprises, easier onboarding) at no extra time cost here, many teams break the tie in favour of refactoring — but strictly by the time-arithmetic alone, it is a genuine coin-flip. That is exactly why the rule uses a strict $<$ : it only fires when there is a real, positive time saving.

PICTURE. A balance scale: teal $P$ on one pan, orange $n C_{0} i$ on the other. Whichever pan sinks lower is the more expensive path — pick the lighter pan; if they balance, it is the break-even tie.

Step 7 — The edge cases (never leave the reader guessing)

Case A — cold code, $n = 0$ (you'll never touch it again). Right side $= 0 \cdot C_{0} i = 0$ . The rule needs $P < 0$ , impossible ( $P \geq 0$ ). So never refactor. ✅ Matches intuition: why clean a room you're about to demolish?

Case B — very hot code, $n \to$ large. Right side $n C_{0} i$ grows without limit while $P$ stays fixed. Eventually $P < n C_{0} i$ is always true ⇒ always refactor high-traffic code. ✅

Case C — no mess, $i = 0$ . Right side $= n C_{0} \cdot 0 = 0$ . Rule needs $P < 0$ ⇒ never "fix." ✅ There's nothing to fix; $i = 0$ means the code isn't actually slowing you down.

Case D — free fix, $P = 0$ . Rule becomes $0 < n C_{0} i$ , true whenever $n > 0$ and $i > 0$ ⇒ always do a costless cleanup. ✅ Of course — a free improvement is pure win.

Case E — the tie, $P = n C_{0} i$ . The two towers are exactly level. Strictly, the rule does not fire ( $<$ is false), so pure time-cost says "indifferent." ✅ You lose nothing either way; tip-breakers (safety, morale) decide.

PICTURE. The orange interest tower drawn at four heights (n=0, small, large) against a fixed teal $P$ line — you can see the crossover point where the decision flips, and the exact height where they balance (break-even).

Step 8 — Plug in real numbers (the parent's worked examples, visually)

PICTURE. The two main examples as two little scales — Example 1 tips toward "refactor," Example 2 tips toward "keep."

The one-picture summary

Everything above, compressed: the clean bar $C_{0}$ → stretched by mess into $C_{0} (1 + i)$ → repeated $n$ times → the orange interest tower $n C_{0} i$ → weighed against the teal principal $P$ . When teal is lighter, you refactor; when they balance, you're at break-even.

Recall Feynman retelling — the whole walkthrough in plain words

Every time you edit code, it takes some days — call the clean amount $C_{0}$ . If someone took a shortcut earlier, you have to dig through the mess first, so it takes a fraction $i$ longer — that extra dig-time is the interest. One dig is no big deal. But if you'll come back $n$ times, you pay that dig-tax $n$ times over, totalling $n C_{0} i$ — a tall orange tower of wasted days. Instead you could stop once and clean the mess for good; that one-time cleanup costs $P$ — a teal block. Both paths still make you do the real work $n C_{0}$ , so that part cancels — leaving just a race between $P$ and $n C_{0} i$ . If cleaning ( $P$ ) is cheaper than all that future digging ( $n C_{0} i$ ), clean it. If they're exactly equal, it's a wash — flip a coin (or lean on the fact that clean code is nicer to live with). If the code is cold ( $n = 0$ ) or already clean ( $i = 0$ ), the orange tower is zero-tall, so never bother. That single comparison, $P < n C_{0} i$ , is the entire art of managing technical debt.

Recall Quick self-check

What does $i = 0$ do to the repay rule, and why? ::: It makes $n C_{0} i = 0$ , so $P < 0$ is required — never satisfied. Meaning: if the mess causes no slowdown, there's literally nothing to repay. In Example 1, what is the net saving from refactoring? ::: $n C_{0} i - P = 10 - 6 = 4$ days. Why is the interest a multiplication $n C_{0} i$ rather than a big sum written out? ::: Because every visit costs the identical tax slice $C_{0} i$ , and adding an identical thing $n$ times is multiplication by $n$ . What happens at the break-even point $P = n C_{0} i$ ? ::: Both paths cost the same total time — you are indifferent; the strict $<$ means the rule does not fire, so tie-breakers (safety, quality) decide. Why does the base cost $n C_{0}$ drop out of the comparison? ::: It appears on BOTH sides (the real work you do either way), so subtracting it from both sides cancels it — only $P$ vs $n C_{0} i$ decides.

Flashcards

In the repay rule, what does the orange "tower"

n C_{0} i

represent?

The total future interest — extra days wasted across all

n

future changes if the debt is not fixed.

What is

C_{0}

in the walkthrough?

The time one change takes if the code were perfectly clean — the yardstick everything is measured against.

Why does the interest use a fraction

i

(a multiplier) instead of a fixed added time?

Because a shortcut slows work in proportion — a bigger change suffers more, a tiny change less — so the penalty is a fraction

i

of the clean cost

C_{0}

, giving a messy change of

C_{0} (1 + i)

When

n = 0

, what does the repay rule say and why?

Never refactor — the right side

n C_{0} i = 0

, so

P < 0

can never hold; cold code isn't worth cleaning.

What are the legal domains of

n

i

C_{0}

P

n

nonnegative integer;

i \geq 0

;

C_{0} > 0

;

P \geq 0

What does the break-even case

P = n C_{0} i

mean?

Both paths cost equal time — you're indifferent; the strict

<

leaves the choice to non-time factors like safety and quality.