I go back and forth on whether the name “Tech Debt” is the most useful term. In my book, I decided I can’t fight the term, so I use it, but in my opening paragraphs I make an argument that the problem we call tech debt isn’t like other debt.
The most common way I’ve seen tech debt is that it’s just everywhere. It’s not limited to a specific old module, it pervades the codebase like marbleized fat in a good steak, but not as delicious.
I started writing a book on Tech Debt in January and I posted a few chapters in the Spring. A few months later, Gergely Orosz from the Pragmatic Engineer reached out to ask me to write a guest post for The Pragmatic Engineer newsletter—it just went up today.
https://newsletter.pragmaticengineer.com/p/paying-down-tech-debt
If you want updates about the book, sign up here: Pay down tech debt to go faster right now
There are a lot of posts on this site about tech debt. Here are a few
Over time I have become skeptical of most dependencies. I wrote in Third-party Dependencies are Inherently Technical Debt:
[…] any third-party dependency is technical debt. Third-party? Here’s how I am defining it for the purposes of this article. You are the first party, the platform you are writing on (e.g. iOS, Android, React, NodeJS) is the second party. Everyone else is third party.
[Third-party dependencies are debt because] you need to constantly update them, […] they introduce breaking changes, […] they become unsupported, […] your platform adds their own incompatible implementation, [… and] they don’t update on the same schedule as the [platform].
To that end, I like policies that tend to reduce the number of dependencies you have. Here are a couple that I have seen work.
Seems like extra work, right? The extra work is why they work.
Today and Saturday is the annual NERD Summit at UMass Amherst. I attended nearly every year when I lived in Western Massachusetts and still volunteer by maintaining the official NERD Summit conference iOS app (App Store), which is open-sourced (NERD Summit on GitHub).
If you are nearby, head over.
At Trello, on the mobile team, we had a formal way of allocating engineering time to either working on PM-led or Engineering-led initiatives.
A PM-led initiative was something that ultimately rolled up to a OKR that was well-understood by the business. The requirements came from the PM and the PM could assess acceptability. An Engineering-led initiative was something like tech debt, changing our dependency package manager, improving CI build times or anything where the requirements came from the team itself and the PM didn’t know or care about it (and neither did anyone outside the team).
So, let’s say we decided the split was 60% on product manager led initiatives and 40% on what we called engineering-led. The split is arbitrary—the EM and PM agreed on what was appropriate for their team and set it for the year.
Then, any individual engineer at any one time (for a couple of sprints) was on either a PM-led project or an Engineering-led project. We did not want a single engineer to be split across PM/Eng-led work. This made it easy to know we were allocating correctly (without having to track time on individual stories or cases).
So, if it was 60/40 and we had 10 engineers, 6 would be on PM-led, and 4 would be on engineering-led at any one time, but it rotated.
This just needed to be mostly right over the course of a year—on any specific month it could be a little off if over the long-term, it matched. For example, If the PM didn’t have work ready, we could do more engineering-led work temporarily.
On June 25, 2012, I tweeted:
I believe I just coined a new programming term: if-bomb: adding a bunch of heinous if’s for a special case “Dropped an if-bomb on my code”
To be clear, this is a well-known anti-pattern, covered in Patterns of Enterprise Application Architecture by Martin Fowler. I started calling them “if-bombs” to discourage their use. One remedy is the Special Case pattern, but there are others. A special case of the Special Case pattern is the Null Object pattern, which is used when the special case handles null references.
When I begin a coding session, I start by taking the task I need to do and breaking it down in fine detail. For example I am working on personal productivity system, which has a “Project” concept. In my first pass, Projects just had a name field. I was just working on getting the relations right. Now, I want to flesh it out a bit. I have a Jira issue with the title: Add “color”, “startDate”, and “endDate” fields to Projects.
Here’s how I break that down:
I could get more granular, but this is about the level I like. I put them in my task manager to keep me on track and to make sure I’ve thought the problem through. This will roughly be the order I do it and the commits I make.
It guides the session and keeps me on track. If I don’t finish, I just move the incomplete tasks to the next day, which lets me preserve some of the momentum from the previous one. Also see: Green, Refactor, Red, where I end the session with a failing test for the next task I want to do.
Chapter 1 of Joel Spolsky’s User Interface Design for Programmers is titled “Controlling Your Environment Makes You Happy” and contains a story of Joel’s time working in a bakery which concludes:
The more you feel that you can control your environment, and that the things you do are actually working, the happier you are.
This is why I Use My First Commit to Fix CRAP. It takes 5-10 minutes and lets me exert some control on my environment. I start each day with a small success. If I feel frustrated later in the day, I just do it again.
I saw a suggestion to use Subject-First Commit Messages to make it easier to scan the log. I switched over to this about two weeks ago and like it.
When you write commit messages this way, they tend to result in passive voice sentences like “Project cleared from project prompt dialog when closed” and “Title added to date prompts”. Many style books suggest that you not use the passive voice, which is then repeated as a rule. But, the passive voice is useful, and is often used by the best writers (go check your favorite). Even those style books (like Strunk and White) give exceptions.
When writing a sentence, it’s important to control the subject. In most commit messages, the implicit subject is the programmer. For example, in “Added title to date prompts”, the subject “I” is dropped. Since we know that the programmer is making the commits, we don’t need to constantly repeat it. It’s better to pick the most important noun in the sentence and make that the subject, and to do that (in English) you have to use the passive voice.
I talked about this in Write While True Episode 37: The Passive Voice Was Used. If you want to see a thorough take-down of anti-Passive Voice zealots, watch Larry McEnerney analyses the Gettysburg Address, which I discuss in the podcast episode.
The second discipline in The Four Disciplines of Execution (4DX) is to act on the lead indicators to accomplish a big and important long-term goal. To practice this discipline, pick some short-term thing that you could do at any time. You have to design it so that continuously achieving the lead indicator would eventually build up and achieve the long term goal. For example, I want to publish a book by June 30, but what I track is the number of days I work on it each week—my goal is five per week. Every day, I have a choice to do this. It’s a metric I can move at any time. I think it’s very likely that if I accomplish this goal every week, I will have a book by June 30.
The third discipline helps you stay on track by asking you to build a scoreboard that lets you know if you are winning. I track my lead indicators in my journal and with some software that I am working on. I also decided to use the Chronicling App on my iPhone to make it extra visible as a widget on my home screen. The scoreboards need to be visible enough so that you are constantly reminded of it. The bulk of my day is spent NOT working on the book, but I want to keep it top of mind so that I can put in at least an hour each day.
I would love to apply this to tiny tech debt payments. This is something I try to do almost every day, guided by the Tech Debt Detectors in my Editor. The work ends up in commits that go into the PR I’m working on because they are targeted in the area I am trying to change.
The commit is the leading indicator. Over the course of months, they will result in a cleaner codebase that is easier to work on. Each one contains a refactoring or a new test, but not every refactor or test counts. When I am doing TDD or just testing as I go, that’s not a debt payment. Neither is cleaning up a PR for review or removing a TODO in the grace period. So, I can’t just look for commits that add tests or commit messages with the word “refactor”.
To track these commits, I will use the string “[payment]” in the commit messages. My scoreboard is just:
git log --oneline | head -10 | grep -i '\[payment\]' | wc -l
which would show me the number of commits in the last 10 that were payments. My goal for now is that it not be 0. I run yarn lint and yarn test constantly, so I could just make them report the number.
If you are on a team working on a messy codebase, then adopting something like this gives you agency every day to make some kind of difference. If you do it, then invest the time to make a central scoreboard to make that work visible.