A developer is asked to add another language to a website. The translations are ready, so it sounds like an afternoon’s work. Days later the team is still changing templates, error messages and integrations where language choices were hardcoded. A decision that once saved time is now making every change more expensive.
This fictional example captures the real question behind technical debt: not whether the code looks old, but what an earlier decision costs today and who can decide whether to change it.
Technical debt is not another word for bad code
Martin Fowler describes technical debt as a metaphor for design decisions that make future work more expensive. His quadrant distinguishes prudent from reckless and deliberate from inadvertent debt. A small initial implementation can be a sensible choice. Even careful teams discover better designs as they learn. What matters is whether the consequences remain visible.
The cost appears during the next change
The website originally served one language and one team. Now editors need translations, but each component implements language settings differently and tests do not cover every variant. The cost is more than a one-off refactor: every release demands extra checking and creates a greater chance of regression. “Clean up old code” is therefore a weak backlog item. Explain which change is harder, which user journey is affected and which operational risk is increasing.
Record the reason before it gets lost
An Architecture Decision Record (ADR) preserves the context, options, decision, rationale and consequences of an architectural choice. A consciously temporary solution can also have an owner and review trigger. Our fictional team could have recorded: “We launch in one language, but revisit the content model when a second is required.” That is an illustrative decision, not a real project record.
Not every debt deserves immediate repayment
Fowler points out that paying down debt may not be worthwhile when its ongoing cost is tiny, for example in rarely changed code. An unsupported runtime with serious security implications is different from an old but stable internal component. Repeated manual releases may merit automation before a complete rewrite. Assess change frequency, incident impact, effort and the risk of intervention rather than simply modernising everything.
Test the boundaries that cause trouble
Integrations are a useful example. An API connection can work perfectly until its provider becomes temporarily unavailable. Without appropriate retries, idempotency or monitoring, failures can spread. Focus tests on meaningful failure scenarios, contract boundaries and recovery; an impressive code-coverage percentage alone does not prove those paths are reliable.
Turn frustration into an observable improvement
For the multilingual website, a better outcome than “refactor templates” is: “A new language can be configured without changing presentation components, and missing translations follow a documented fallback.” Assign ownership, identify how to verify the result and measure whether later changes really become easier. That makes technical debt an explicit product decision.
The problem is losing sight of the trade-off
Technical debt will not disappear: requirements evolve, teams learn and earlier solutions age. The goal is to know which compromises were made, what they cost and when repaying them creates more value than postponing the work.
web architecture knowledge hub · integration mistakes in growing organisations (BlazeForce, sponsor).
Sources
Contact us
Tell us how we can help; we will respond within two working days.
