Resume for Steven E. Newton


Readings for Code Janitors


Steven E. Newton
Crater Moon Development
© 2003-2023

Deep Into Technical Debt

19 Nov 2022 579 words. (3 min)

Technical debt is anything done today knowing it will make code harder to change later.

Well, then, what isn’t tech debt? Doesn’t everything we do today, in some respect, increase the effort to change it later? So we must mean “harder than it would normally be,” but… what is normal? You can try to use velocity to get a sense of it, but you can’t meaningfully estimate the long-term cost of not doing something now.

I recently re-read some of the literature on technical debut and listened to a video of Ward Cunningham – who first documented the concept – discuss what it means. It turns out the concept is frequently misunderstood, almost as frequently as refactoring is misunderstood.

Technical debt is not “let’s hack something together now, get it to work no matter what, and come back and make it better later”. A debt is something you can pay off later, over time. Shoddy work is a sunk cost. You can’t pay it off.

While debt can be described as “deficiencies in internal quality”, but those deficiencies are not the same as shoddy code. A deficiency in choosing to use a partial solution because it is easier to implement than the preferred solution doesn’t mean you implement the partial solution badly. There’s also a place for choosing a solution you believe is correct and ideal, then finding out later, as the project progresses, where and how the solution fails in light of new information.

Technical debt is deferred necessary work. track decisions to defer work, eg. in ADRs, tickets in the bug-tracking system, or big pink cards on the planning wall

What is necessary work? Cleaning up whatever will slow you down in the future. When do you pay off the debt? Just before fixing a bug or adding a feature. Now we see why crap code is not technical debt. You can’t confidently fix bugs or add features when the code is garbage. You have to throw out the garbage first, which means you’re starting over, not cleaning up.

Martin Fowler says it’s not possible to choose to write bad code now to speed up a bunch of features to delivery. As soon as you start adding features, you run into more friction as a result of the cruft. You end up spending more time doing work of low quality than if you’d done it as well as you could, though incomplete.

Ward Cunningham has described tech debt as about writing code before you fully understand the problem and a solution. It’s not about writing bad code, it’s about writing the best code you can within your incomplete understanding. You must still express your understanding of the problem as best as you possibly can. If you do not express your understanding clearly now, in the future you will surely not be able to understand what you meant. You will not remember, and poorly-written code will not express your past understanding.

As an example, let’s say you create a class Passenger, but you slapped together without clearly communicating your understanding. In the future, when you have a better understanding, it won’t be clear what it’s trying to do, so you have to spend time refactoring the code until it reflects something meaningful. If it had been meaningful in the first place, you’d be in a better position to know where to make the change.

Watch out for teams using technical debt as an excuse to do shoddy work.

<-Writing as a Programmer Fred Brooks ->