Let's not call it "tech debt," it's just "mess"

A few months ago I wrote about one of my methods for dealing with "technical debt" and I had to cut a huge throat-clearing section from the opening about how I don't really like the term "tech debt" as a metaphor. Obviously I'll use the term it when I'm talking to other software developers, but I try to avoid it when I'm talking to people in "the business." It's useful when it's used correctly, but usually when software developers say "tech debt," what they really mean is something more like "mess." This is a common enough usage that even when "tech debt" would be appropriate, people who aren't software developers but work with software developers often hear "mess," and they'll start to develop the impression that "tech debt" is something that developers say when they did their job poorly, or don't like how the previous team did it.

The problem with "tech debt" as a metaphor is that businesses like debt. There's such a thing as "the right amount" of debt for a business. It's not zero. When you don't take on enough debt, you're either too reliant on more expensive forms of capital like equity, or you're not growing as fast as you could have. You're leaving too much money in the future, where it's useless to you.

Financial debt is predictable. When you take some on you know exactly how much you've taken and how much it's going to cost you. You have a little piece of paper with all the terms written on it. You don't accidentally take on debt. It doesn't suddenly become more expensive than you thought it was going to be because you haven't taken on that kind of debt before.

Some of what people talk about when they talk about technical debt meets this criteria. For example: When I initially wrote most of the SQL queries for StoryTime, I didn't think very much about performance. I organized the queries based on what made the code easy to read, and ended up mostly mapping a single query to a single assign. I knew at the time that at some point, when there were even more queries and more people using the application, I would eventually need to go back and condense those operations to reduce the number of distinct database calls in order to improve page load performance. I took a "loan" from the future to make developer a little easier in the future.

Most of what people call "technical debt" doesn't even speed up development. Some of it is just sloppy or unskilled work. Arguably even my example above meets this criteria: This is the first time I've built a project with this framework that deals with this much SQL. The second or third time I build an application of this type, I might just build it with a single query that fetches everything the page needs from the beginning.

The classic example of "that's not technical debt, that's just mess" is slow, unreliable, or insufficient tests. If you're good at writing tests it's not actually any harder to write tested code than untested code, and the benefits to project velocity accrue immediately. Writing fast tests and reliable tests are also strictly a matter of craft. If you know the techniques for making tests fast and reliable then it's easy to write fast and reliable tests. It's not "debt" to not know how to do something.

Other times people say "debt" to mean "this isn't to my taste." I've known teams that decided their proliferation of container images was "technical debt" and spent a few weeks consolidating them into one image. Then a year later and with some new personnel on the team, they decided that having a single container image for everything was "debt" and broke it up into a bunch of focused images.

I'm not against aesthetic judgements. They're underrated in our field. I don't even think either version of that team necessarily did the wrong thing. But "this work is organized in a certain way that has tradeoffs I don't like," isn't "debt."

My biggest problem with the metaphor, though, is the cost predictability part. "Debt" implies that the cost of the decision can be understood at the time this is made. In my experience this is very rare with technical decisions. The vast majority of what I've seen called "technical debt" was not well understood when the team first made the decision to take it on. Usually at the time it seemed like a minor efficiency, or even "doing things the right way." Only later did they discover that the choice had some kind of explosive property.

For example: I've done a lot of consulting on systems that were event-driven using AWS Lambda. Typically the team that builds these systems would have a lot of experience with doing something similar with a monolithic, request-driven architecture, and a lot of experience with painful scaling problems. They've read about event-driven systems and they've decided they would have much better scaling properties than the request-driven system they built the first time. So when they get a second chance, they go all-in on events. I usually come in at the point where no one understands how the event-driven system works, because it turns out it's very difficult to trace a particular customer action through to the part of the system that's failing in a system like this, and because no one had ever built a system like this before they didn't know how to instrument it correctly to deal with that problem. Oh, and, by the way, the system handles about half an event per second.

That's not technical debt. That's buying private credit because your financial advisor recommended it, only to realize later that you can't take your money back out for thirty years.

The problem with saying "technical debt" in these situations is it makes you look unserious. If you use "technical debt" to mean "a problem we didn't realize would be there when we made this decision" it makes you look like you take on debt without reading term sheets. Maybe in a better world software developers would always know what the costs are of the decisions we're making at the time that we make them, but that's not the way the industry is structured. Software developers are usually doing things right at the edge of our own experience. It's normal to be surprised by the results.

Personally I prefer the term "mess" and I prefer the metaphor of "maintaining a home or a workspace." A software project is also a workspace, and there's a certain amount of cleaning and tidying up and reorganizing that's required as we go along. Sometimes we organize our tools by function and then realize that, actually, it would be easier to find what we need when we need it if they were sorted by size. Sometimes we have a hard time letting go of things that don't bring us joy and it gets hard to manage the clutter. Sometimes we've taken over a house from a previous owner and it needs a lot of work, but we need to live in the house in the meantime.