Technical debt — types, managing
WHAT is technical debt?
Key distinction: debt is NOT the same as a bug. A bug = wrong behaviour. Debt = code that works but is hard to change, understand, or extend.
WHY it accumulates (first-principles reasoning)
Software has a quantity called understandability/changeability. Every shortcut lowers it. Let:
- = cost to make a future change,
- = cost if code were clean,
- = interest rate per change (the fractional slowdown the mess causes),
- = number of future changes touching that code.
Then total extra cost paid because of the shortcut is the accumulated interest:
TYPES of technical debt (Fowler's Quadrant)
Martin Fowler classifies debt on two axes: was it deliberate or inadvertent, and reckless or prudent?
| Reckless | Prudent | |
|---|---|---|
| Deliberate | "We don't have time for design." | "We must ship now and deal with consequences (and we know what they are)." |
| Inadvertent | "What's layering?" (didn't know better) | "Now we know how we should have done it." |
Common practical categories:
- Code debt — duplication, dead code, bad naming, no tests.
- Design/architecture debt — wrong abstractions, tight coupling, layering violations.
- Test debt — missing/flaky tests ⇒ fear of changing code.
- Documentation debt — stale or missing docs.
- Dependency debt — outdated libraries, unpatched versions ("software rot").
- Infrastructure/build debt — slow CI, manual deploys.
HOW to manage it
The workflow:
- Make it visible — keep a debt register/backlog, add
// TODO/FIXMEtags, use static analysis (SonarQube), track a debt ratio = remediation cost / development cost. - Quantify — estimate principal and interest (from the formula above) to rank items.
- Prioritise — fix debt in code you change often (high ) first. Leave cold code alone.
- Pay down — strategies:
- Boy Scout Rule: "leave code cleaner than you found it" (continuous small repayment).
- Dedicated %: reserve e.g. 20% of each sprint for refactoring.
- Refactor-before-feature: clean the area you're about to extend.
- Prevent — code review, definition-of-done, automated tests, linters.
Common mistakes (Steel-man + fix)
Recall Feynman: explain to a 12-year-old
Imagine your room. You're in a hurry so you shove everything under the bed instead of putting it away. Now your room looks fine and you finished fast — that's the shortcut. But every time you need a sock, you have to dig through the whole pile under the bed (that's the interest — extra effort each time). If you'll need socks every day, it's worth cleaning up properly now (paying the principal). If you're moving houses tomorrow and tossing it all anyway, just leave the pile! Good programmers don't keep their room perfect — they keep the stuff they use a lot tidy, and leave the rest.
Flashcards
What are the two financial parts of technical debt?
Who coined the "technical debt" metaphor?
Give the rule of thumb for when to repay debt.
Is technical debt the same as a bug?
Name the two axes of Fowler's technical-debt quadrant.
Which quadrant is "healthy" debt?
What is the Boy Scout Rule?
List four types of technical debt.
Why is "eliminate all debt" wrong?
What metric measures debt size in static analysis?
Why does ignoring debt cause a "debt spiral"?
Connections
- Refactoring — the primary tool to pay down principal.
- Code Smells — observable symptoms that signal debt.
- Unit Testing / Test Driven Development — reduces test debt and makes refactoring safe.
- Software Maintainability — debt is a maintainability cost.
- Agile Sprint Planning — where you reserve % capacity for repayment.
- Coupling and Cohesion — high coupling is a major source of design debt.
- Continuous Integration — infrastructure debt lives here.
Concept Map
Hinglish (regional understanding)
Intuition Hinglish mein samjho
Dekho, technical debt ka idea bilkul loan jaisa hai. Jab tum jaldi mein code ka shortcut maar dete ho — bina test likhe, ganda design, copy-paste — to feature toh fast ship ho jaata hai, lekin uske baad har baar jab us code ko chhuoge, extra time lagega. Wo extra time hi "interest" hai, aur usse properly theek karne ki cost "principal" hai. Yaad rakho: debt bug nahi hai — code bilkul sahi chal sakta hai, par agar use change karna mushkil hai, to wo debt hai.
Sabse important baat: saara debt khatam karne ki koshish mat karo, kyunki cleaning mein bhi cost lagti hai. Simple rule: . Matlab agar code ko aage bahut baar chhuna hai (n bada), to abhi fix karna sasta padega. Agar ek baar use karke phenk dena hai, to debt rakho — refactor karna paisa waste hai. High-traffic code pehle clean karo, cold code ko chhodo.
Manage kaise karein? Pehle debt ko visible banao (TODO/FIXME, SonarQube, ek debt backlog). Phir quantify aur prioritise karo. Pay-down ke liye "Boy Scout Rule" use karo — jis code ko chhuo use thoda saaf chhodke jao — ya har sprint mein 20% time refactoring ke liye reserve rakho. Aur Fowler ka quadrant yaad rakho: sirf Deliberate + Prudent debt achhi hai (soch-samajh ke liya, ticket banaya). Baaki teen — bina plan ke liya gaya debt — usually problem banta hai.
Bottom line: debt ko ignore mat karo, warna "debt spiral" mein phas jaoge — code slow karega, slow hone se aur time nahi milega repay karne ko, aur problem badhti jaayegi. Control rakho, eliminate karne ke chakkar mein mat pado.