What technical debt really is, and when to pay it back

Almost everyone in software uses the phrase technical debt, and almost everyone uses it to mean the wrong thing. They point at some code they find ugly, or a system that is hard to work with, and call it technical debt as if the label explains anything. It does not. Most of what gets called technical debt is just bad code, and the two are different in a way that matters for every decision you make about when to fix things. Real technical debt is a deliberate choice, made on purpose, knowing the cost. Understanding that difference is what lets you keep debt on purpose instead of collecting too much of it by accident.

Here is how we actually think about it, and how to decide what to pay back and when.

Technical debt is a choice, not a mess

The term was first explained as a comparison with a loan, and that comparison is the whole point. When you take on technical debt, you build something the quick way instead of the right way, on purpose, to move faster right now. In return, you agree to pay extra later, like interest on a loan, in the form of slower future work, until you fix it properly.

That word "deliberate" is what separates debt from a mess. If an engineer writes tangled code because they did not know better or were rushing carelessly, that is not debt. That is a mistake, and the fix is to prevent it, not to schedule a repayment. Debt is when you look at a clean way and a quick way, understand what each costs, and choose the quick way because releasing this week is worth more than releasing it perfectly next month. You knew. You chose. You wrote it down. That is a loan, and taking a loan can be a smart choice.

Why does the distinction matter so much. Because if you call every piece of ugly code debt, you lose the ability to tell a decision you can defend from a problem you should have prevented. A team that took shortcuts on purpose to meet a launch date made a business choice. A team whose code is a mess because nobody decided anything made no choice at all, and no amount of "we'll pay down our tech debt" planning will fix a habit of not deciding.

Smart debt versus reckless debt

Not all debt is equal, and the difference between the good kind and the bad kind comes down to three things: was it chosen, was it recorded, and can you pay it back.

Smart debt is a shortcut you took on purpose, that you wrote down somewhere the team can see, in a place you can fix later without rebuilding the whole system. You skipped writing the flexible version of a feature because you were not sure anyone would use it, you left a note saying so, and the shortcut is in one small part of the code. If it turns out to matter, you fix that one part. That kind of debt is a tool, and healthy teams use it all the time to release on time.

Reckless debt is the opposite on every count. Nobody decided to take it, so nobody owns it. Nobody recorded it, so nobody remembers it is there until it breaks. And it sits under a part of the system that much else depends on, so fixing it means changing everything built on top. This is the debt that actually hurts, and it usually builds up without anyone noticing, one un-decided shortcut at a time, until a whole area of the code becomes something engineers are afraid to touch.

There is a special case worth naming, because it surprises people. In machine learning systems the debt is larger and harder to see than in normal software. Researchers at Google pointed out that the model, the clever part everyone focuses on, is only a tiny fraction of a real system, and most of the long-term cost is in the data pipelines, the code that connects the parts, and the tangled dependencies around it. If you are building anything with ML, assume the debt is bigger than it looks, and mostly in places you are not looking.

When to pay it back

Here is the mistake engineers make in the other direction: treating all debt as something to eliminate. It is not. The right question is never "is there debt here." It is "is this debt making my work slower in a way I can notice."

Fix debt when the extra work it causes starts costing more than the fix. That usually looks like a shortcut in a busy part of the code, the part that changes every week, where the old workaround now makes every new feature slower to build and riskier to release. When engineers start saying "I can't add that cleanly because of how this was done," the extra cost has grown large enough that fixing it is worth it. Fix it then, and fix it before you add more features on top, because debt under a part of the system that much else depends on gets more expensive to fix the longer it stays there and the more code depends on it.

There is also a deeper reason to fix problems early rather than late, and it is not just about debt. The cost of fixing a defect rises the later you catch it, a pattern that the NIST work on software quality has long described. The same logic applies to debt: a shortcut caught and fixed one week after it was written is cheap, and the same shortcut left under six months of new code is expensive. This is the same idea behind releasing in small steps, which we wrote about in move fast without breaking the product: small increments keep problems small and cheap to fix.

When to leave it alone

Now the part most "pay down your tech debt" advice gets wrong. Plenty of debt is fine to leave alone, and fixing it is wasted effort.

Debt in code that rarely changes causes almost no extra work. A rough shortcut in stable code nobody has touched in a year is not slowing anyone down, so fixing it gives you nothing except tidier code, which does not help you release the product. The goal is not zero debt. Zero debt is impossible, and a team that tries to reach it moves too slowly to release anything. A product that never releases because the code is finally perfect is worse than a product that releases carrying some debt.

So the skill is choosing what to fix first. Know where your debt is, know which parts are in busy code that much else depends on and which are in code nobody changes, and spend your effort only on the shortcuts that are actually costing you. Leave the rest. You will keep some of it forever, and that is exactly how it should work. Keeping debt on purpose is not failure. It is how real products get built on real timelines.

How to talk about it without the code

The last piece is communication, because a lot of the trouble with technical debt is that engineers and the business do not understand each other. Engineers deal with the extra work every day and struggle to explain it. The people who set the priorities hear "we need time to clean up the code" and treat it as optional, behind the features that make money.

The loan comparison is how you explain it. Do not describe the code. Say you took shortcuts to meet a deadline, that like a loan they now have a cost, and that the cost is showing up as slower releases and more bugs in a specific part of the product. Tie it to something the business already feels. "The last three features in this area each took twice as long as they should have, because of a shortcut we took to launch on time, and I want two weeks to fix it so the next five are fast again" is a sentence anyone can judge. It has a cost, a cause, and a benefit, all in plain language.

And make the decision shared. Engineers know where the debt is and what it costs. The business knows what the next few months have to deliver. The best teams put fixing debt into normal planning as a visible line item, decided together, instead of something engineers do in secret and feel guilty about. Debt taken on purpose, recorded openly, and fixed on a schedule you both agreed to is not a problem. It is just how a well-run team uses one of its most useful tools.

A newer kind of debt

There is a form of this that hardly existed three years ago and is now common: code that works, passes its tests, and nobody has read.

It does not look like debt. The usual signs are missing. It is well formatted, it follows the conventions, and it has no obvious mess. But debt was never really about how code looks, it was about the gap between what a system does and what your team understands about it. Generated code that was released without a careful review creates that gap immediately, in large amounts, and without anyone noticing.

You pay the cost the first time something breaks and nobody can say why the code does what it does. You fix it the same way as any other debt: someone reads it properly and writes down the intent. Which is why we do the reading before the merge rather than after the incident.

Sources

• Sculley et al. (2015), "Hidden Technical Debt in Machine Learning Systems," NeurIPS: https://papers.nips.cc/paper/5656-hidden-technical-debt-in-machine-learning-systems
• NIST, software quality and testing research: https://www.nist.gov/