Technical Debt and the In-Laws Metaphor

This week we're talking about one of those topics that divides opinions in every development team: technical debt. And I'll start with the question I always ask in my trainings:

Is technical debt bad?

Spoiler: No. But there's a catch.

The Myth of Technical Debt

Technical debt isn't bad per se. It's a strategic tool we can use to deliver value sooner and learn from it. The problem isn't using it -- it's not understanding its associated costs.

Online you'll find plenty of definitions using financial metaphors. I prefer explaining it with something more tangible: the kitchen.

The In-Laws Metaphor

Picture this scene: you're relaxing at home when the phone rings. Your in-laws are coming for dinner. In 30 minutes.

Time to juggle. Between you and your partner, you improvise the best you can: a starter, a main course, a dessert... But there's no time to clean up. So you do what any reasonable adult would do: shove all the dirty dishes into the drawers.

They arrive, they eat, they compliment the food. Mission accomplished.

The next morning you go to make breakfast and... a drawer full of dirty utensils. Now you have two options:

1. Invest time cleaning everything up now (and possibly be late for work)
2. Ignore it and leave it for later (when the problem might be worse)

That's technical debt.

To help you avoid this, I've prepared a visual guide that will help you identify, prioritize, and most importantly, explain technical debt to people who don't write code:

A Real Case: The Printing Labels

On the team I supervised at Mercadona Tech, we experienced this firsthand with the warehouse label printing code.

The code had evolved erratically over years. With every new requirement, a new patch. We had massive templates with printer-specific commands, no abstractions, no semantic tests.

How did we test changes? We'd generate the template, copy the code, send it to a physical printer, and review the printed output. If it looked right, great. If not, start over.

Each change was a micro-loan at sky-high interest. The first one was barely noticeable, but after a year, the "interest" we were paying in the form of slowness and errors was greater than the benefit of the original shortcuts.

The Breaking Point

The day came when we needed a quick change for a trial run. The code was tangled, poorly tested, held together with duct tape. We raised the flag: this wasn't going to be easy and it carried risk.

We made the change. The trial went fine. But the next day we had an incident because we'd broken an edge case and warehouse preparation was compromised.

The fix was simple (deploy the previous version), but it was an important wake-up call for both developers and the business.

We'd moved fast all those years taking shortcuts without paying the bill. Now we were in trouble.

The Solution: From Chaos to a DSL

The sensible thing was to acknowledge the problem and fix it. Instead of continuing with overly complex templates and free-form text that broke with a misplaced semicolon, we created a DSL (Domain Specific Language) around the document.

We went from having printer-specific commands mixed with business data to having objects that represented clear concepts: a QR code, a text block, an image. Each with well-defined properties.

Immediate benefits:

• Declarative label composition
• Semantic testing (we tested objects, not strings)
• Robust translation to printer commands
• Accelerated development
• Changing labels stopped being painful

The key is balance. Being a Senior means:

1. Being pragmatic enough to know when to move fast by taking shortcuts
2. Being responsible enough to know when to stop and clean up the kitchen

The Prototype vs. Production Rule

A tool that works very well for me is differentiating between:

• Prototype code: Code where we've taken shortcuts to validate an idea, deliver initial value, or start learning from our users. We treat it as such: a prototype.
• Production code: Code ready to be maintained long-term, tested, with appropriate abstractions, and prepared to evolve.

The important thing is that everyone speaks the same language. That the team and business understand that with that code we've cut corners and that the feature "isn't finished" until it's transformed.

Once the value is delivered and users and business are happy, we transform that prototype code into production code.

This allows us to:

• Get the benefits of generating technical debt (speed, learning)
• Keep the negative impact under control
• Not compromise the long term

Negotiating with the Business

Managing technical debt isn't just a code issue -- it's also a cultural one. It involves uncomfortable conversations, consensus on priorities, and honest communication within the team.

You need to translate debt into real cost: "This code makes us lose X days on every change" or "We've had Y incidents because we didn't fix it" are arguments the business understands.

What experiences have you had with technical debt? Share it on Twitter or LinkedIn -- I love reading your stories.