Managing technical debt extraction within a large code base

So often, we have to make decisions in the thick of things that we are unhappy with. Either it’s because we have other dependencies we are waiting on to finish, or because we have ran out of time, sometimes you just have to implement something crappy to get the job done.

The problem comes when we go back to excise those pieces out, often, if we leave ourselves any clues at all, it will be something like this:

And that’s it! That’s our grand plan. I’m sure whoever left that message meant well, and if they read it, they may even know what it means… if they still work at your company.

Now, my proposal isn’t actually that different. There’s just a step or two more you need to add.

First, your gating item needs a ticket. If you are waiting on the memcache server to be brought up, there had better be a ticket for the task of bringing that memcache server online. We will call this ticket OPS-1234. Next, create a technical debt ticket which DEPENDS on OPS-1234. We will call this new ticket TDBANK-4321. Side note: I like the tech debt ticket ‘stub name’ to be TDBANK because it reminds you that you are in fact taking out a loan against your long-term sanity, and encourages you to … repay it … as quickly as possible.

Now that we have our two tickets, it’s time to make our comment:

Not only do you see WHAT you are waiting on, but WHY, and every dependency of the gating issue is tied back to TDBANK-4321, which means you ONLY have to look at TDBANK-4321 to see if you can complete the instrumentation, and uncomment the pending code changes.

I have been encouraging this technique for the last year, and it has been shown to be beneficial on multiple occasions. Sure, it does “clutter up your code base” with todos and ticket numbers, but informed developers make better decisions, and tracking intentional tech debt becomes MUCH simpler if you decide to explicitly document when and why you make those decisions.

I see technical debt in the same light that I see version control and server configuration management: you are going to do it whether you want to or not. So choose to do it explicitly and take control of your process, before your tech debt takes control of you.

Leave a Reply