Technical Debt

The metaphor

Taking a shortcut is like borrowing: you ship sooner, but you owe the cost of doing it properly later. The interest is the extra time every future change takes because of the shortcut. Some debt is deliberate and sensible, for example a quick version to learn whether a feature is wanted. Debt becomes a problem when it is never repaid or even recorded.

Where it comes from

• Deadlines and scope pressure.
• Skipped tests, documentation or code review.
• Copy-pasted code and unclear names.
• A design that no longer fits what the system has become.
• Outdated dependencies, frameworks or runtimes (see Dependency Risks).
• Knowledge that lives only in one person’s head.

Not every flaw is debt. Debt usually means a conscious trade-off, or a known gap between how things are and how they should be. Sloppy work done by accident is a quality problem.

Signs you are looking at it

• Small changes take surprisingly long or break unrelated things.
• People avoid certain files or say “don’t touch that”.
• Workarounds, TODO and HACK comments, and temporary code that became permanent.
• New team members need a long time to become productive.

What to do about it

• Write it down in the backlog or an issue, with the cost and risk. Complaining about it in conversation does not get it prioritised.
• If you take a shortcut knowingly, say so in the pull request and leave a note that someone can trace back to the reason.
• Repay gradually: improve code as you work on it (see Refactoring Basics), and ask for time for larger items.
• Start with debt in code that changes often. It costs more than debt in code nobody touches.

Estimates should take existing debt into account (see Estimation Basics).

Try it

Look through a codebase for TODO, FIXME and HACK comments. Pick one, find out why it was added and how much it costs, and write a short issue describing it and what fixing it would involve.