You measure technical debt in two layers: the numbers a code analysis tool reports, and a written register of the debt those tools can't see. Then you translate both into time and risk, because that's what the people paying for the system can weigh against new features.
Technical debt is anything that makes the next change slower or riskier than it should be. Ward Cunningham coined the term in 1992, and we covered his original description, along with ten everyday examples, in technical debt examples.
Much of what you'll read on measuring it comes from vendors that sell the dashboard. Their numbers are real, but narrower than the name suggests.
- Measure technical debt in two layers: the numbers a code scanner reports, and a written register of the debt no scanner can see.
- SonarQube's technical debt figure estimates the effort to fix all code smells. Its debt ratio compares that effort with the cost to build the code.
- Scanners miss architecture problems, untrusted tests, manual releases, platform support dates and knowledge held by one person.
- Explain debt in time and risk, such as "every release takes an extra day because of this," not in ratios or letter grades.
How does SonarQube measure technical debt?
SonarQube publishes exact definitions for its metrics. These come from the SonarQube Server 2026.5 metric definitions, checked on 16 October 2026.
- Technical debt (sqale_index) is "A measure of effort to fix all code smells." Code smells are maintainability problems in the code itself, such as duplicated blocks, overly complex methods and dead code.
- Technical debt ratio (sqale_debt_ratio) is "The ratio between the cost to develop the software and the cost to fix it." The formula divides the technical debt by the cost to develop one line of code multiplied by the number of lines of code.
- Cost to develop one line of code is predefined. The default is half an hour, and you can change it.
The ratio then sets the maintainability rating:
| Rating | Technical debt ratio |
|---|---|
| A | Up to 5% |
| B | 5% to under 10% |
| C | 10% to under 20% |
| D | 20% to under 50% |
| E | 50% and over |
How to calculate the technical debt ratio: an illustrative example
Take an illustrative codebase of 50,000 lines. At the default of half an hour per line, the tool treats the cost to develop it as 25,000 hours. If the tool estimates 1,500 hours of effort to fix all code smells, the ratio is 1,500 divided by 25,000, which is 6%. That rates B.
Two things follow. The ratio scales with size, so a large codebase can carry a lot of debt in hours and still rate well. And the figure rests on the half-hour assumption: change that setting and every rating moves. The numbers are good for tracking a trend and poor as a price tag.
What tools measure, and what they miss
By its own definition, that figure counts code smells. Code smells matter, but they're often not why a system is hard to change. The expensive debt usually sits around the code. Our code audit checklist covers each of these areas in more detail.
| Kind of debt | Do code scanners see it? | How to measure it instead |
|---|---|---|
| Code smells: duplication, complexity, long methods | Yes. This is what they're built for | Scanner numbers, tracked as a trend |
| Architecture problems: tangled modules, a database every application writes to | Mostly not. Code rules look at files and functions, not whole systems | Count how many components a typical change touches, and draw the dependencies |
| Missing or untrusted tests | Partly. Coverage shows what ran, not whether the tests check the right things | Ask how many releases still need manual checking, and which tests get ignored |
| Manual release steps | No | Write down every manual step and time one release from merge to live |
| Platforms past or near vendor support | Partly. Dependency scanners flag old library versions, not your vendor's support date | List each runtime, framework, database and operating system with its support end date |
| Knowledge held by one person | No | For each part of the system, name who can change it safely |
How to identify technical debt the tools can't see
Start where change is slow or risky, and work back to the cause.
- Version history. Files that change most often, or always change together, show where debt costs you every week.
- The team's workarounds. Ask each developer what they avoid touching and why.
- Estimates that keep overrunning. Repeated overruns in one area mean something there is in the way.
- Incidents. Ask what made each recent outage or rollback possible.
- Support dates. Every component near or past the end of vendor support is a debt item with a date on it.
Keep a debt register
Each item the tools miss goes into a register, one row per item, written so someone outside engineering can read it. The rows below are illustrative.
| Item | Where it lives | What it costs each change or release | Risk | Date attached |
|---|---|---|---|---|
| Config edited by hand on every deployment | Release process | About half a day per release | Outage if a step is missed | None |
| Discount rule coded in two services | Pricing and invoicing | Every pricing change made twice, then reconciled | Invoices disagree with quotes | None |
| Database version past vendor support | Database server | The upgrade gets bigger every year | No security fixes | The vendor's end-of-support date |
| Month-end job only one person understands | Finance reporting | Every change waits for that person | Nobody can fix it if they leave | Their planned retirement, if known |
Put the register in the same backlog as feature work and review it when you plan each quarter, so the business weighs each item against new features instead of meeting it during an incident. Across many applications, score the portfolio first and start with the worst corner.
How to explain technical debt to executives
Don't lead with the ratio. A rating of C means little to the person approving the budget. Translate each item into time and risk instead. The figures below are illustrative.
- Instead of "the debt ratio is 14%," say "every change to billing takes about a week longer than it should, because the same rules live in three places."
- Instead of "the runtime is end of life," say "from the vendor's end-of-support date, the system that takes customer payments gets no security fixes."
- Instead of "we have a knowledge silo," say "if one named person is on leave at month-end, the close is late."
Then attach a decision to each item: fix it now, schedule it, or accept it knowingly. Executives can make that call when the cost is in hours and the risk has a name, but not from a letter grade.
If the business wants a money figure, multiply the hours an item costs each month by what those hours cost you, and give it as a range. Once the register exists, reducing the debt becomes a planning question rather than an argument.
What the 30-day assessment adds
A scanner gives you the first layer quickly. The second layer takes someone reading the code and the system around it.
That's the job the 30-day assessment does for one system. It's fixed in scope, at a price agreed before we start. Over 30 days we go through the codebase and its architecture, map how the system fits together, find the hidden architectural debt that scanners don't report, and flag the security and compliance gaps. The report says in plain language what is broken and what it would take to fix it, in terms you can carry into a debt register.
Your team can pay the debt down from the report, or we can do the work as a separate project with its own scope and price. The report is useful without the second part.
To ask whether it fits your system, send one sentence about it to spaudel@aicoservices.com.