3 Kinds of Technical Debt

krakjn · 4 min read
technical-debtengineeringarchitecture

Technical debt isn’t one thing. It’s three—and you can carry all of them at once. Each looks different, costs different, and demands a different fix. Here are the debts I’ve watched sink more ships than any single bad deploy.

Debt 1: Patch Becomes Production

Quick fixes, temporary workarounds, commented-out code with TODO markers drifting like flotsam through the codebase. You tell yourself:

  • “We’ll clean this up next sprint”
  • “It’s just a temporary workaround”
  • “I’ll write tests for this later”
  • “Let’s hardcode it for now”

This one is so easy to do, everyone does it. The issue isn’t the patch, it’s the fact that you never get around to fixing the patch. Refactoring is a healty process that should be done every sprint, but often gets neglected. Code is a living breathing thing, and with enough neglect parts of the codebase die off. It’s like lack of air suffocates entire sections of code. When other engineers join a decaying codebase their first thought isn’t “Hey, I’ll just refactor all of this because I know the original intent”, it’s more like “Oh man, who wrote this? Yeah.. I am gonna just patch it”. When enough of these patches get into the code you will have some true legendary monstrosities. I had a friend who has a PHP file reach into the 20+ thousand lines with tons of redundancy. I call this coderot and it will fester and spread until it takes over the whole codebase. Eventually leading to the dreaded rewrite.

Ways to prevent coderot:

  1. Every sprint, do refactoring. I wanna see red PRs!
  2. Every one feature, remove two patches. Pay it down slowly…
  3. Have an entire sprint dedicated to “debt payment”, the one who pays the most down gets a prize!

Debt 2: Golden Architecture

It goes like this: a talented developer sees the opportunity to build The Perfect Tool™: “Why have multiple specialized tools when one grand system could do it all?” Highly configurable, handles every edge case, “future-proof”, the list goes on. What happens when the Architect goes on PTO or leaves the company? You are left with a behemoth of a thing nobody understands. And now “The Perfect Tool™” is in everything, it’s everywhere, you can’t escape it.

  • Documentation that reads like hieroglyphics
  • Configuration files that could fill a library
  • Abstractions wrapped in abstractions
  • A system so flexible it lost its purpose
  • A maintenance nightmare that needs a full crew to understand

The irony: this debt often comes from your best engineers doing the right thing, building cathedrals where chapels would suffice.

Ways to prevent Super Tools:

  1. Absolutely the smallest scope should be the target.
  2. Don’t write a docker wrapper tool, because everyone is too lazy to learn docker. It will never be 1:1! just learn docker
  3. Do not write wrappers of other tools for ease of use, this will cause confusion and burden
  4. Just like a function, do one thing and do it well.
  5. Ask yourself honestly, do you need this?
  6. If you have the need of a super tool, then dedicate money, time, and resources to it properly

Debt 3: Cognitive Debt

In the age of Artificial Intelligence with an AI chat bot that can write code for you it’s great, until it’s not. This one is so insidious. I fell for it too. You open up your AI enhanced IDE set it to “plan mode” and you prompt to a SPEC.md. You glance over the code, it passes the tests, it does what you need it to. I did this recently on a project for work. I even shipped it becuase at first glance everything was solid. Then I used it… A small bug, okay let me take a look. After taking a closer look the code was an overcomplicated mess. Redundant logic, over engineered ideas, the intent was totally off. So I decided to turn off the AI and go on a 5 hour bender of refactoring. I had so much fun but the most important part was I understood what was going on again. Also because I was in the headspace of writing the code I was able to:

  1. Debug faster
  2. Add features quicker
  3. Understand the quirks deeply
  4. Enjoy the process of coding again

Ways to prevent comprehension debt:

  1. Turn off the AI every now and then
  2. “Hand write” a feature
  3. Walk through every line the bot presents
  4. Use it as a semantic checker versus an idea creator
← Back to Log