The Engineer’s Complete Guide to Technical Debt

Alexandre Omeyer
Alexandre Omeyer
12 min read
In this guide, you'll learn metrics, statistics, and tools that help engineering teams manage technical debt and accelerate their software development process.

Technical debt is a complicated subject. The world often carries negative connotations with images of student loans, medical bills, or mortgage payments often coming to mind. In reality, though, some financial debt can actually help people.

The same thing is true with technical debt.

Technical debt – also known as tech debt or code debt – often refers to a rushed development process or a lack of shared knowledge among team members. However, in many cases technical debt is inevitable and is part of any software development process.

Like financial debt, tech debt can either harm or help your organisation. In order to use it wisely, engineers and team leaders must monitor how much technical debt they acquire and learn to manage it well. This can become a difficult task for organisations, especially when they do not have the right processes, metrics, and tools in place.

This guide I will help you answer the following questions:

  1. What is technical debt?
  2. Why does technical debt occur?
  3. How to address technical debt?
  4. What are some technical debt metrics you can use to measure success?
  5. What are the best tools to fight technical debt?

Let’s get started!

What Is technical debt?

Software professionals fight over the technical debt metaphor because metaphors have a natural openness to them. Ward Cunningham, the developer of the first wiki and co-author of the Agile Manifesto, first used the tech debt metaphor simply as an illustration.

Cunningham has elaborated on the concept since first using the metaphor decades ago. In one popular video posted in 2009, he explains that...

“With borrowed money, you can do something sooner than you might otherwise... I thought borrowing money was a good idea, I thought that rushing software out the door to get some experience with it was a good idea, but that of course, you would eventually go back and as you learned things about that software you would repay that loan by refactoring the program to reflect your experience as you acquired it.”

Today, we can say with certainty that technical debt is unavoidable and many dev teams are acquiring it for good reasons. This leads us to a simple version of a tech debt definition:

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

Why does technical debt occur?

In many cases, technical debt happens because Engineering team need to meet deadlines and rush software development process.

But that's not the only reason. It's important to remember that tech debt is inevitable and appears in any software project at some point. Dealing with technical debt in an ongoing basis will help your team avoid large pieces of debt.

Large pieces of technical debt occur when:

  • A company culture doesn't support tech debt heroes and code quality enthusiasts
  • The process of dealing with tech debt is tedious (e.g. all issues go to Jira backlog)
  • Engineers find it difficult to justify time and money spent for technical projects, e.g. refactoring
  • There's no awareness on technical issues in the codebase
  • Codebase issues are not linked to code and, hence, are hard to find
  • There are no tools and resources available for Engineers to deal with technical debt

How to address technical debt?

The best way to deal with technical debt is to work on it continuously and make it easy for your Engineering team to (1) see codebase problems, (2) report and log these problems, (3) prioritise and fix them.

I described some of the best strategies to prevent technical debt in my latest article.

The most important steps include:

  • Making it easy for your team to track and view technical debt
  • Having a space for your team to discuss your codebase issues
  • Integrate your tech debt work into your existing workflow

If you already have an endless backlog in Jira or your other PM tool try out the free Stepsize VSCode and JetBrains extensions. They help Engineers track technical debt directly from the editor and add codebase issues to your sprint.

This method allows you to link issues to code, get visibility on your tech debt, and collaborate with your teammates on maintenance issues without leaving your editor and switching context.

What are the technical debt metrics?

Justifying the time and money spent on technical debt will be difficult unless you have a prove and can measure success.

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

Here are some of the best metrics to look at:


At the very least, software developers should be counting and keeping track of their bugs. This includes both fixed and unfixed bugs.

Noting the unfixed bug allows development teams to focus on and fix them during their Agile iterations. Noting the fixed bugs helps teams measure how effective their tech debt management process is.

Code Quality

While bugs have a more direct effect on the software’s end-users, code complexity can really damage the development team and the organization as a whole.

Look for code complexity metrics like…

  • Cyclomatic complexity
  • Class coupling
  • Lines of code
  • Depth of Inheritance

The lower each of these measures, the better.

Keeping an eye on these metrics also helps organisations know exactly which code to rework or refactor in order to reduce complexity and improve the backend side of the software.

Code Cohesion

Like code quality, focusing specifically on code cohesion will help the code from getting too complex. A high code cohesion usually means that the code is more maintainable, reusable, and robust. It also minimises the amount of people who need to get involved in the code, which can greatly reduce complexity and decrease the chances of bit rot.

High cohesion is when you have a class that does a well defined job.

Code Ownership

More engineers usually means more cruft, and more cruft often leads to greater problems and higher levels of unintentional technical debt. That’s why code ownership is such a valuable metric: it answers the question, “who is focusing on what code?” If something breaks, who do you call?

This metric will give your project management eyes on the amount of people working on various pieces of code. Knowing this information will enable these teams to reduce the amount of people and time dedicated to these efforts. You don’t want one person owning a complete section of code - just in case they get ran over by a bus or, in a better scenario, a new job. Usually, the right level is for teams of engineers to own domains in the codebase.


Code 'churns' when it gets rewritten / replaced. It's a measure of the activity a given piece of code sees. You want to give special attention to code that sees a lot of activity because any problem in there will be exacerbated. Measuring churn, then, helps teams recognise and prioritise what parts of the code require refactoring. If engineers have to constantly address bugs around the same part of the code, that means something is going wrong over there. Watching for that churn will help organisations pinpoint those problems more quickly, allowing them to fix the problem with a permanent solution that keeps tech debt down.

Keeping track of these tech debt metrics will not eliminate all your debt, but it will help you manage it more effectively.

Codebase issues created VS resolved

You want to track the number of tech debt issues created and fixed. To do that, you need to track tech debt issues separately from your other issues.

Logging your issues in Jira or other PM tool creates a problem every Engineer is familiar with:

  1. Issues are logged
  2. Issues lack context
  3. Issues can’t be prioritised
  4. Backlog becomes overwhelming
  5. Repeat

Therefore, you need tools that are designed specifically for tracking and prioritising technical debt.

What are the best tools to fight technical debt?

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

Here are some of the best tools:

1. Technical debt issue tracker in your editor

Devs spend most of their time in the editor and that's the best place for them to create technical debt issues.

Stepsize tool is designed specifically for Engineering teams to track and prioritise technical debt directly in their VSCode or JetBrains editors and allows you to:

  • Create & view code issues directly from your editor
  • Prioritise code improvements like technical debt
  • Add key issues to your sprints with our Jira integration

It's a great tool for building a process for addressing technical debt continuously, getting all of your technical issues visible in your editor, and collaborating with your team members on fighting technical debt.

2. Git analysis tools

Static code analysis tools like Codescene help Engineering teams analyse the code to detect defects and vulnerabilities. You will see hidden risks and social patterns in your code and get actionable insights automatically.

3. Code quality tools

Code quality tools like SonarCube, Codacy, and CodeClimate Quality are powerful ways to scan your codebase to find hotspots you might want to improve. These tools run an automatic analysis of your legacy code or raise issues during the development process.

Note that all automatic tools are great as the first step but are totally divorced from business context and won't help you build a process for resolving technical debt continuously.

Additional information

How is technical debt used in scrum/agile?

Scrum has become a popular framework for software developers to use as they seek to deliver their products in a more efficient manner. One key principle with Scrum is that things are unpredictable: customers change their minds and new needs arise often. This openness to change means that technical debt will likely occur when using the Scrum framework.

One Scrum trainer – Stefan Wolpers – talks about two different types of tech debt in Scrum.

  • First is the active choice to create a short term solution consisting of less-than-perfect code so that you can deliver the product more quickly. The expectation is that the development team will go back and improve the code quality after the initial release.
  • The other type of tech debt happens more passively as the development team discovers more information about the problem they’re trying to solve. As new needs arise, solutions that worked yesterday may not work tomorrow. The code requires adjustment and refactoring, and in this way, it contains a certain amount of debt.

Wolpers points out that the Scrum Guide does not give any specific guidance regarding technical debt. It offers no “silver bullet,” as he puts it. Despite this, he also recognises that accruing technical debt is an inescapable part of the business, and suggests 6 ways for Scrum teams to better handle their code-based financials.

According to Wolper, Scrum teams should…

  1. Prioritise transparency with technical debt. Transparency, says Wolpers, makes managing technical debt much simpler. He recommends that teams prominently display a visualisation of their technical debt to keep it at as a front-of-mind priority and that they review their tech debt needs during every Sprint meeting.
  2. Track tech debt. Wolpers suggests counting bugs and using more in-depth code metrics like cyclomatic complexity, code coverage, SQALE-rating, and rule violations if possible.
  3. Pay back debt quickly and regularly. Like financial debt, technical debt is best managed when teams pay back their loans on a regular basis. Wolpers says that Scrum teams should consider allocating 15-20 percent of their resources to refactoring code and fixing bugs every sprint cycle.
  4. Align product backlog. Your product backlog should include tasks related to paying back technical debt. Organising your debt into what you want to tackle this sprint will help keep the debt from falling through the cracks and being forgotten about.
  5. Adjust your definition of “done.” Don’t count something as finished until it meets a set standard for manageable tech debt.
  6. Standardise procedures. Develop a repeatable formula for how your team handles adding experiments or new features that include the introduction of technical debt.

What are the different types of technical debt?

Technical debt can take on many different forms, and people like to argue about the differences.

At the very least, most experts agree on two different types of technical debt: intentional and unintentional. Steve McConnel gets credit for recognising this distinction in 2007, but it is similar to Wolper’s separation of active and passive technical debt for Scrum users.

Intentional tech debt (also called deliberate or active) occurs when organisations choose to leave room for improvement in their code for the sake of reducing time-to-market.

Unintentional tech debt (also called accidental, outdated, passive, or inadvertent) happens when the code quality needs improvement after a period of time. This could be the result of poor production the first time around or simply the natural need for updates as code becomes outdated.

One academic paper published in 2014 titled “Towards an Ontology of Technical Debt” rejected the idea of only two types of tech debt. They felt that organisations would be better served if their technical tech had more specific categories, so they came up with 13 different types of technical debt, each including the specific problem within the title:

  • Architecture Debt
  • Build Debt
  • Code Debt
  • Defect Debt
  • Design Debt
  • Documentation Debt
  • Infrastructure Debt
  • People Debt
  • Process Debt
  • Requirement Debt
  • Service Debt
  • Test Automation Debt
  • Test Debt

While these separations have offer specifics, the most popular way of categorising debt comes from Martin Fowler’s Technical Debt Quadrant. Like Ward Cunningham, Martin Fowler was one of the 17 authors of Manifesto for Agile Software Development. When it comes to technical debt, however, Fowler went solo and developed what he calls the “Technical Debt Quadrant.”

What is Martin Fowler’s Technical Debt Quadrant?

In 2009, Fowler nuanced the twofold separation of intentional and unintentional technical debt popularised by Steve McConnel. He felt that people used the debt metaphor to ask the wrong questions.

Instead of trying to dig out an answer to technical questions about design flaws like “is this considered technical debt or not?”, Fowler wanted to know if the debt these software systems accrued were reckless or prudent. This distinction, coupled with the idea of “deliberate” or “inadvertent” debt created what became known as 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

The inadvertent and deliberate debt is the same as intentional and unintentional: deliberate debt happens as a choice in creation and inadvertent comes after the fact when teams need to make adjustments.

The prudent and reckless distinction is a bit more unique, though, and this piece gives the quadrant its value. Prudent tech debt comes from a team that knows what it’s doing while reckless debt accrues when people have just been too sloppy.

Fowler shows this distinction in the following graphic:

Can you see the difference between the prudent and the reckless?

The prudent team understands the moves they make. They’re using their tech debt intentionally.

The reckless team just treats their software system like an American Express cardholder on a shopping spree. The debt just keeps coming.

Fowler does note that the most complex part of the quadrant to explain with the debt metaphor is the Prudent-Inadvertent cell. This comes when a team knows what they’re doing and does a good job on the project but still ultimately needs some reworking later on.

All software engineering teams, he says, should expect some level of this debt no matter their expertise or experience. A little debt, when prudent, is to be expected, but that just makes it all the more valuable to keep the reckless debt down and to reduce the bad code as much as possible.

What Type of Tech Debt Should Always be Avoided?

Prudent tech debt can have a lot of benefits for software organisations, but these same organizations should keep an eye on how much reckless tech debt they accrue. The reckless is never good, but another form of technical debt exists that can harm organisations even more: bit rot.

Bit rot (also called “software entropy”) happens when software deteriorates over time to the point of creating errors or even altering its functionality and usability. Bit rot takes time to develop, but it can create a huge head for development teams.

It usually happens when developers make small, incremental changes to legacy code that they don’t fully understand. These small changes eventually create enough complexity and problems that the whole software gets affected. Some engineers may even violate NFR (Non-functional requirement) or break the code entirely. The only way to fix this type of tech debt is to refactor the whole thing.

The biggest problem here in terms of debt is that the small changes actually contribute to the total amount of debt, and most of the time, the teams don’t even know it. Using Wolper’s concept of transparency can help organisations avoid such a disaster.

Likewise, teams would benefit from fully understanding each piece of software they work on so that they do not unintentionally add code that can hinder the system. Project management teams can keep their developers accountable by making sure their development processes do not leave room for bit rot to occur.

What Are Tech Debt Statistics?

A handful of academic studies and surveys have been conducted that shed light on the software industry’s view of the technical debt metaphor.

One industry survey from Carnegie Mellon’s Software Engineering Institute found that the majority of participants found some value in the metaphor though they had slight discrepancies of specific definitions. Even more intriguing, however, is their findings regarding what contributes to technical debt.

Respondents said that poor architecture choice was the primary source of their technical debt. Second was overly complex code, and third was closely tied between a lack of documentation and inadequate testing.

These results show that most of the respondents accrued debt unintentionally. What’s worse is that 65% of participants said that they had no process in place for managing their technical debt. This means that they accrued tech debt because of a lack of strategy and have chosen not implement a strategy to fix it!

One software developer who has over 20 years of experience working with all sorts of companies, from Fortune 500s to startups, suggests that organisations should invest in their tech debt like they would invest in paying off credit cards. He says that organisations should focus their investment in two places:

  1. Their company culture
  2. Their codebase

Investing in the company culture looks like getting everyone on the same page. It means putting systems in place that keep people accountable. It means knowing what people are working on.

Investing in the codebase may mean performing more in depth and more frequent quality assurance tests. These tests may even be automated. It could also mean more frequent refactoring, especially if your organisation has already accrued a good deal of tech debt. At the very least, investing in your code base should include some form of code reviews to make sure that the problems get solved before they get way too out of hand.

Investing in these places are great places to start, but the most valuable thing any organisation can do is manage their technical debt. Without a clear strategy for doing so, the debt will just keep rising and create more problems further down the line – like it did for those companies from the survey.


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, making it easy for your team to track and prioritise codebase issues, have regular tech debt discussions, and use tools that are designed specifically to help you fix technical debt.

No items found.
No items found.