Manage technical debt: How to shine a light on issues in your code base

This article was last updated in October 2019

As large software projects creep closer to looming deadlines, pressure to ship on time and under budget forces teams into trying to deliver too much too soon. Inevitably, this results in imperfect code that negatively impacts software quality.

The next set of requirements bounces into view, and before you know it “we’ll fix it later” becomes a company culture that promotes an unhealthy and counterproductive way to build software.

Bigger projects get added to the schedule, and issues present in production get baked into the layers of code, accumulating into what many teams know as ‘technical debt.’

The thing about technical debt is that we know every large codebase has it, but the question is, to what extent?

Unfortunately, ignorance isn’t bliss.

What technical debt is (and what it isn’t)

Imagine your desired outcome is a finished two storey house. You build the first floor, but poor planning and time pressure forced a less than ideal start. The foundation wasn’t quite right, and someone wasn’t thorough with tying loose cables! But, the project must go on.

The customer changes their mind and wants to build a skyscraper instead. You don’t have time to remove the first floor, so you just continue to build. The architect doesn’t like the look of things and wants a 17th century mansion. So what you end up with is an extremely unstable, unsafe and frankly scary looking building:

Like any debt, the technical kind will come back to bite you, and it won’t be pretty. You have to pay it back at some point. You can’t control external requirements but you can choose to architect correctly in response to them, and when to do so.

Technical debt can’t be avoided altogether of course. There’s no perfect system due to the tradeoffs that must be made, and attempting to ship gold-plated code every time isn’t scalable, contributing to delays.

We can however increase visibility on how much technical debt is being accumulated, and from there begin to be more proactive about fixes by improving the processes that lead to the technical debt in the first place.

Your end users and key stakeholders will thank you for it.

How to recognise technical debt levels

Because technical debt is a metaphor (albeit a useful one), discovering the causes and fixing them is not an exact science. There’s almost always more technical debt in a project than you think. As developers move from project to project under ever-present deadlines due to market realities, technical debt begins to accumulate.

Team leads don’t spend as much time in the code base as they used to, obscuring their visibility on the health of the company’s applications. Individual developers may be tempted to default to hacks and workarounds to meet their estimates and deadlines.

Tell tale symptoms appear as a result of technical debt in the project:

• Software bugs
• Performance and quality issues
• Difficulty extending existing implementations
• Estimates not lining up with deliverables
• End users complaining and higher support costs
• Increased churn rate for SaaS businesses
• Staff burnout

To reduce the likelihood of these negatives occurring, re-evaluating the processes that lead to them is a good first step.

Take a look at your processes

It may pay to consider a tick-tock mentality where a series of feature additions are completed, then a period for software errors/stability/performance is allowed. During this time, refactoring components is essential to ensuring improvements scale and are integrated and extensible with the larger system.

Extra time for software errors/stability/performance improvements put your team back in control, so you can choose when to pay back technical debt.

After paying back your debt, systems will often gain breathing room and be future-proofed for growth. The code base will be ready for the next round of features and requirements.

Make improvements

Software bugs and performance issues are simply the inevitable side effects of concerns that come about during the development lifecycle. Therefore the only way for technical leads to recognize tech debt is to accept you have it – it’s a matter of to what extent.

To get a measure of the extent of the damage, get feedback from the people in the code all day long. Do you find intermediates and seniors mentioning code smells, tricky refactorings, or frequently coming across a sea of edge cases? Are ops awake at 3AM every few days?

In other words, where are the main pain points for your team? Get them to give estimates for fixing those pain points and front load the work. Start to build a culture of quality first, and provide an environment where your team members feel comfortable bringing up issues they get a bad feeling about.

As visibility into the health of your software improves, it becomes more fulfilling for your development team to write good, solid code. It suddenly becomes fun to take an investigative approach into things like software errors and actually have fun in a problem solving environment.

Measuring technical debt is like measuring the length of a piece of string – pretty impossible. But now we’ve built a relationship between technical debt and something measurable (like software errors), we’ve added an element of quantifiability – technical debt’s arch nemesis.

How to provide benchmarks to get all your team on the same page

Rushed deadlines, crunch times and poor tooling are sure fire ways for code quality to suffer. There is a need to present a well structured argument for saying “let’s delay this feature.”Or even “let’s invest in better tools to support our growth” or “I need more resources to fix bugs and rearchitect.”

So now we know the symptoms of technical debt, we can start to provide benchmarks around improving those symptoms.

What are the symptoms of technical debt?

You can’t measure technical debt, it’s far too vague. But you can measure software errors, performance, and the general health of your software. This will give you a start point to getting a handle on your technical debt.

Don’t worry about metrics being granular; perfect code is not the aim here. However, don’t forget even small improvements to page load speed will increase the likelihood of someone using your application for longer.

We go into detail about which KPIs you should be measuring for peak software performance in this article. In summary, we hold our leadership team accountable to four major metrics:

• Users affected by bugs
• Median application response time
• P99 application response time
• Resolved bugs

Measuring and improving these KPIs will give your end users fast software and result in less software crashes. From here you can start allocating your resources to addressing accumulated technical debt where it’s affecting your business most – at the end user level.

A note on visibility

Measuring tech debt is the first step to getting your team in the spirit of consistently creating great code. Making the metrics visible to your entire team will be the final nail in technical debt’s coffin

Raygun’s dashboard feature can help shine a light on the symptoms of technical debt

Stimulate conversation in your team around errors, performance issues and KPIs. People notice when numbers on a screen improve, and as people talk, you may find your technical debt starts to repay itself, your code base becomes more manageable and more enjoyable to work with. Getting clear on the impact of technical debt will also make it easier to communicate that value up the chain.

Here is a short video on technical debt from our Tech Leader’s Lunch series with AWS on communicating technical debt to leadership.

The end of technical debt?

Not quite. A level of technical debt is an inevitable side product of our fast paced software world. But don’t let your tech debt remain unquantified! It’s too easy for people to wash their hands of responsibility.

Technical debt is everyone’s problem, and once you surface the issues, fixing them is far easier.

Raygun’s Dashboard feature creates stunning visual representations of the health of your software. Make your technical debt visible to the whole team and watch as your end users get a better experience.