The Engineer’s Complete Guide to Technical Debt

“Technical debt” has an image problem, like student loans or mortgage payments. But acquiring technical debt can be a good decision, in the same way that taking out a financial loan can be. 

In this guide, we’ll answer the following questions:

1. What is technical debt?
2. What types of technical debt are there?
3. Why does technical debt occur?
4. What’s the impact of technical debt?
5. How should teams manage tech debt?
6. What are the best tools to manage technical debt?

What is technical debt? 

Just like financial loans, the cost of technical debt can be a good deal in exchange for shipping faster. 

Ultimately, tech debt – also known as tech debt or code debt – is inevitable and is part of any software development process.

What matters is that we accumulate debt prudently, manage it properly and have a plan to pay it back.

This leads us to a simple version of a tech debt definition:

Technical debt is any code that you've decided is a liability.

An important note about preventing tech debt

Many people ask us, “how do we prevent tech debt?”

This is often not the right question. Why? Because it comes from the assumption that tech debt is a bad thing. 

Don’t get me wrong. It can be a bad thing. But let’s go back to our analogy with financial debt. Sometimes taking out a financial loan is simply necessary. We might use that loan to make home improvements or start a business. Many loans are good decisions.

So really, we want to ask…

• “How do we prevent taking on bad technical debt?”
• “How do we decide when it’s good to accumulate technical debt?”
• “How should we manage existing technical debt”?

We need to understand why tech debt occurs to deal with it effectively. And to do that, we need to talk about types of tech debt.

Understanding the different types of tech debt

Technical debt has been characterised in several ways over the years. The approach has shifted from two types of tech debt in 2007 – intentional and unintentional debt – to identifying no less than 13 types in 2014. These included architecture debt, defect debt, people debt and test debt.

Today, the most popular way to categorise tech debt comes from Martin Fowler’s Technical Debt Quadrant.

What is Martin Fowler’s Technical Debt Quadrant?

Fowler doesn’t want us to focus on whether something should be considered tech debt. Instead, he wants us to ask whether a debt is prudent. He coupled this with the “deliberate/inadvertent” distinction and used this to create the Technical Debt Quadrant.

The quadrant creates four different types of technical debt:

• Reckless and Deliberate
• Reckless and Inadvertent
• Prudent and Deliberate
• Prudent and Inadvertent

Prudent tech debt accrues when a team understands the debt's context and the repayment terms.

Reckless tech debt accrues when the inverse is true.

The prudent team uses their tech debt intentionally and has a plan to pay it back.

The reckless team treats their software system like a credit card with no direct debit to pay it back.

The tech debt you need to be worried about is the tech debt which is undocumented, unmanaged or has spiralling debts, or in other words, increasingly negative impact.

Why does technical debt occur?

Now we’re ready to answer why teams accumulate tech debt a little more deeply.

There are a number of ways that tech debt might originally accumulate that might not be directly linked to shipping faster, such as:

• Using outdated tech
• Poor architectural choices
• Over-complex code
• Insufficient testing
• Lack of skills

Tech debt becomes a problem when it isn’t tracked properly. When it isn’t tracked, it accumulates much faster and can have an exponential impact. A few factors influence tech debt growth linked to poor tracking:

• Issue invisibility – Codebase knowledge is locked away in engineers’ heads, or there’s simply no awareness of technical issues.
• No code quality culture – Company culture doesn't support tech debt heroes and code quality enthusiasts.
• Poor process – Dealing with tech debt is tedious (e.g. all issues go to the Jira backlog).
• Low time investment – Engineers find it hard to justify the time and money spent on technical projects, e.g. refactoring.
• Lack of context – Codebase issues aren’t linked to code and, hence, are hard to find.
• Poor issue tracking – Engineers have no tools and resources to deal with technical debt.

These all have a root problem – low-quality issue tracking. We’ll come back to this later.

‍

Understanding the true impact of tech debt

The impact of tech debt extends deeply into engineering resources and broadly across different parts of an organisation’s ecosystem.

Tech debt gets out of hand when there isn’t a good strategy for managing it. Every good strategy starts with good issue tracking. To place this into context, we found that teams who use specific tech debt management tools – in this case, Stepsize – shipped up to 3x faster than teams with no specific tech debt strategy. When tech debt management isn’t planned properly, the overall costs of projects can rise to over 50%.

How tech debt impacts your code

• Complexity – Increasing complexity exacerbates other problems and causes tech debt to accumulate faster
• Bugs – Bugs directly impact the product
• Code quality – Reduced code quality impacts the product and causes tech debt to accumulate faster

Your product

• Functionality – Features fail to work correctly, impacting usability, customer satisfaction and reputation
• Delivery  – Late delivery of products and features impacts customers and teams relying on your delivery, like marketing or sales
• Downtime – Impacts your brand’s reputation immediately
• Risks – Tech debt can increase the risk of serious events, such as data security breaches

Your team

• Slower development speed – Engineers need to spend time working on tech debt, and shipping new features takes longer.
• Team morale – No engineer likes working on tech debt
• Retention – Unhappy engineers are more likely to resign, impacting both your team and HR

Your business

• Customer satisfaction – Tech debt almost always has a negative correlation with customer satisfaction
• Business efficiency – Tech debt makes predictability much harder and impacts systems linked to the product
• Brand and reputation – Once you’ve damaged these, they’re very hard to fix
• Finances – Tech debt itself drives up development costs. The impact of tech debt drives down revenue.
• Survival – We’re talking bankruptcy. No, seriously. Check out our Tech Debt Horror Stories.

More resources:

How tech debt impacts everyone in the company

Learn why shifting technical debt left matters

Calculate the cost of your tech debt 

The symptoms of insufficient tech debt issue tracking

To manage and reduce tech debt, first, we need to track it. 

Tracking issues is a fundamental principle of good tech debt management. Here are some red flags that might indicate that you need to track tech debt better in your team:

If this sounds like your team, don’t worry – we talk to engineering teams daily, and this is exceptionally normal.

Bear this in mind – we’ll come back to this topic shortly.

How to manage and reduce technical debt

How much codebase knowledge is trapped in your key engineers’ heads?

Good tech debt management starts with team-wide excellence at tracking issues.

Leaders need to make it easy for their engineers to (1) see codebase problems, (2) report and log these problems, and (3) prioritise and fix them.

Your goal is to be able to answer “yes” to these four questions:

1. Is it easy for engineers to know when they’re working on code with tech debt? 
2. Is it easy for your engineers to report tech debt?
3. Is there a space for your team to discuss codebase issues?
4. Is tech debt work continuously integrated into your workflow? 

If the answer isn’t a resounding “yes”, your team is at risk of compounding existing tech debt. Next, we’ll look at the best practices top-performing teams need to adopt.

To further explore this topic, read our account of the best strategies for preventing tech debt.

Good issue tracking is the foundation

Transparency is the key to dealing with tech debt. You can’t fix issues you can’t see.

Use issue tracking tools that help your engineers effortlessly add as much context as possible to issues they create. 

Technical debt in agile

To manage tech debt effectively in agile development, teams have to pay back tech debt quickly and regularly. 

Two methods you could use to achieve this include:

• Allocating 15-20% of resources to refactoring code and fixing bugs in every sprint cycle
• Allocating entire sprints to deal with tech debt regularly, such as every quarter

Use a codebase visualisation tool to identify tickets to prioritise. You could base that prioritisation on an area of the codebase or a theme of impact, such as morale. More on tools later.

Adjust your definition of “done”

Don’t count something as finished until it meets a standard for manageable tech debt. It’s okay to accumulate tech debt, but it must be both documented and prudent.

Keep track of tech debt metrics

Tracking key metrics will help you identify tech debt, prove the business case to fix it and track success.

Like any good management plan, organisations need to know the best metrics to help gain control over their technical debt.

These are the tech debt metrics that matter most.

• Debt Index. This is the ratio of resolved issues to total issues. 
• Code Quality. This is an aggregate of several metrics that quantify your code's overall quality and complexity. These include cyclomatic complexity, class coupling, lines of code and depth of inheritance.
• Code Coverage. How many engineers have contributed to each project? 
• Tech Debt Ratio. Used to calculate the overall future cost of tech debt. 5% is a good benchmark.
• Cohesion. Code has high cohesion when most elements belong together and indicates maintainability, reusability and robustness. It helps assess whether your architecture makes sense. 
• Churn. In other words, how often sections of code are being rewritten. It’s an indicator of what’s causing the most bugs.

The following section will cover some tools to help you track these metrics.

More resources:

Read about the three best tactics to prevent technical debt

Learn 8 top metrics for measuring your technical debt

Learn how to run an effective sprint planning meeting to tackle tech debt

Want to prove it’s worth it? Read our complete guide to creating a tech debt proposal.

Tools to fight tech debt

There are plenty of great tools to track and manage technical debt.

There are three areas which benefit most from tooling. We’ll discuss each here.

1. Tracking more, better issues

Devs spend most of their time in the editor, which is the best place to create, view and manage issues. 

Stepsize is a specialised tool which brings issue management right into the codebase. It integrates with your project management tools, like Jira, Linear and Asana.

The tool provides a radically better way to create issues linked directly to code and see how issues impact your codebase (and your team). 

In other words, Stepsize makes codebase issues truly visible and actionable.

‍Learn how to get started with Stepsize here. It works with Visual Studio, VS Code, JetBrains.

2. Git analysis

You want to know about defects and vulnerabilities as soon as they arise. 

A tool like Codescene, a static code analysis tool, helps analyse codebases and spot hidden risks and social patterns.

We love that the insights are immediately actionable.

3. Code quality

Code quality tools are a great first step if you need a starting point. Though they won’t help you build processes for resolving tech debt continuously, they can automatically analyse code and raise issues.

You could look into  SonarCube, Codacy, and CodeClimate Quality if you are looking to review your existing code.

More resources:

Tools to track and manage tech debt

Collaborate better

A lot gets lost in translation (or in the sea of Slack messages) on dev teams.

With. my team, I'm building a tool that helps keep teams on the same page.

It's called Stepsize AI.

Stepsize AI, your AI project companion, brings powerful functionality to your existing workflow platforms. It develops a long-term "memory" of your projects, providing insightful summaries and actionable suggestions about what happens in Jira, GitHub, and Slack.

Stepsize AI can answer crucial questions about your project in seconds, keeping the team aligned and focused on effective decision-making.

Explore the benefits of Stepsize AI.

Rounding up

Leaving technical debt unaddressed can result in many problems in your organisation, such as low team morale, slower time to market, reduced agility because of a poorly designed architecture, and poor security.

To address technical debt, make it easy for your team to track and prioritise codebase issues, have regular tech debt discussions, and use tools designed specifically to help you fix technical debt.