Engineering Practitioner Brief / 18 May 2026
The SonarQube Technical Debt Ratio, Explained
SonarQube is the most widely-deployed static-analysis tool in 2026 and its technical-debt ratio is the most common code-quality number quoted in engineering reviews. This page explains what the ratio actually measures, how to read it without being misled, and how to use it as part of a healthy code-quality practice rather than as a single number to optimise.
The Calculation
The technical-debt ratio is the SQALE ratio implemented inside SonarQube. The formula is simple:
technical debt ratio = remediation_cost / development_costRemediation cost is the sum of the time-cost estimates assigned to each rule violation in the codebase. Development cost is lines of code multiplied by the configurable cost-per-line constant (default: 30 minutes per line for most languages).
For a 100K-line codebase with 2,000 hours of remediation cost, the development cost is 50,000 hours, and the ratio is 4 percent. SonarQube would assign a SQALE rating of A.
The conceptual basis comes from the SQALE methodology by Jean-Louis Letouzey; see SQALE method cost for the underlying framework.
The Five Rating Bands and What They Look Like in Practice
| Rating | Ratio | Typical Codebase Profile |
|---|---|---|
| A | 0 to 5% | Small codebase, recent, or actively maintained with strict quality gates. Less than 12 months old in most cases. |
| B | 6 to 10% | Healthy mid-sized codebase. Established team, active maintenance, occasional rule suppressions. The most common rating for well-run enterprise codebases. |
| C | 11 to 20% | Material debt accumulating. Often a codebase that has been under-invested for 2 to 3 years, or that has absorbed multiple feature pushes without follow-up cleanup. |
| D | 21 to 50% | Heavy debt. Dedicated remediation work needed. Often indicates an organizational debt-pay-down sprint is overdue. |
| E | over 50% | Critical. The codebase usually has structural problems that SonarQube does not measure (architectural debt, missing tests, security debt) in addition to the rule violations. Often a candidate for partial rewrite. |
Industry-wide reports from SonarSource show that typical enterprise codebases land in the B or C band. A codebases are usually small or have aggressive quality gates. D and E codebases are usually old or under-invested. The distribution is roughly bell-shaped centred on B.
What the Ratio Misses
The SonarQube technical-debt ratio is genuinely useful for what it measures, but it is important to know what it does not measure:
- Architectural debt. Wrong service boundaries, missing abstractions, layer-crossing dependencies, monolith-vs-services tension. SonarQube sees individual files and rules, not architecture. See monolith decomposition cost.
- Test debt. SonarQube reports test coverage as a separate metric but does not roll it into the debt ratio. A codebase with A-grade debt ratio and 10 percent test coverage is in worse health than the rating suggests. See test debt cost.
- Documentation debt. Not measured at all beyond commenting rules. See documentation debt cost.
- Dependency debt. SonarQube has limited visibility into outdated dependencies and CVEs (Snyk, Dependabot, and SonarQube's own SCA add-ons cover this). See dependency debt cost.
- Dead code at runtime. SonarQube flags unused private members but cannot see runtime-reachable dead code. See dead code cost.
Clean as You Code: The Modern Quality-Gate Pattern
SonarQube has promoted the Clean as You Code pattern since 2020. The idea: instead of trying to improve the rating on the existing codebase (which is hard, slow, and often political), set quality gates on new code only. A PR can land only if the new code it introduces meets defined thresholds.
The default new-code quality gate in SonarQube blocks merges that introduce: any new bug or vulnerability, more than 3 percent new code with security hotspots, more than 5 percent new technical debt ratio, or under 80 percent coverage on the new code. The thresholds are configurable.
The pattern works because it puts the cost of new debt on the author who is introducing it, at the moment they have the context to address it. Legacy debt is not blocked; engineers touching legacy code only need to keep their changes clean. Over time, as more of the codebase is touched, the rating improves naturally.
Common Rules That Generate Noise
A few rules in the SonarQube default pack generate disproportionate noise without corresponding code-health value. Teams that find their rating dominated by these should consider suppressing or adjusting them:
- Cognitive complexity above limit. Long switch statements that enumerate cases (state machines, parser output, message-type dispatchers) trigger the rule but are often clearer than the alternatives.
- Methods should not have too many parameters. Builder constructors, dependency-injection constructors, and command-pattern objects legitimately accept many parameters.
- Duplicate block of code. Test setup code, validation chains, and DTO mappers often have structural similarity that is intentional rather than extract-method-worthy.
- String literals should not be duplicated. The most commonly-suppressed rule in practice. Tests have many repeated literals (fixture data, expected strings) that have no obvious extraction target.
Reading the Trend, Not the Snapshot
The most useful way to use the SonarQube technical-debt ratio is as a trend line within a single codebase with stable configuration. A ratio that drops from 12 percent to 8 percent over a quarter is meaningful evidence of improvement. A ratio that holds steady while the codebase grows by 30 percent is also meaningful evidence (the codebase is at least keeping up with its growth). A ratio that rises sharply is a flag worth investigating.
What is not meaningful: comparing the ratio between codebases with different rule sets, different cost-per-line configurations, or different languages. The number depends too much on the configuration for cross-codebase comparison to be reliable. Internal trends are useful; external benchmarks are mostly noise.
Related Reading
- SQALE method cost
- Code Climate maintainability score
- CAST Highlight technical debt index
- Types of technical debt
- Technical debt statistics 2026
Frequently Asked Questions
What is the SonarQube technical debt ratio?
The ratio of remediation cost to development cost, calculated using the SQALE methodology. Remediation cost is the sum of estimated fix times for all rule violations in the codebase. Development cost is lines of code multiplied by the cost-per-line (default 30 minutes per line in SonarQube). The ratio is then mapped to an A through E grade.
What is a good technical debt ratio?
SonarQube's default grading: A is 0 to 5 percent (healthy), B is 6 to 10 percent, C is 11 to 20 percent, D is 21 to 50 percent, E is over 50 percent. Industry-wide reports from SonarSource show typical enterprise codebases land in the B or C band; codebases below A are usually small or recently created; codebases above D often have significant architectural problems beyond what SonarQube can see.
What does a 5 percent ratio mean in dollars?
For a 100K-line codebase with the default 30-min-per-line cost, the development cost is 50,000 hours. A 5 percent ratio is 2,500 hours of remediation work. At a $85 per-hour fully-loaded engineer rate, that is $212,500 of potential remediation effort. This is the number to fix everything SonarQube flags; the question of whether to actually fix it all depends on the prioritisation.
What are common false positives in SonarQube?
The cognitive-complexity rule often flags long but logically simple methods (a long switch statement that lists cases, for example). The duplication detector flags structurally similar code that has legitimate reasons to look alike. The 'too many parameters' rule flags builder methods and dependency-injection constructors. These can be ignored or suppressed without affecting actual code health.
How is SonarQube different from SonarCloud?
Same underlying analysis engine. SonarQube is self-hosted; SonarCloud is the SaaS version. Pricing differs (SonarQube has per-developer licensing; SonarCloud is per-LOC for paid tiers, free for open source). The technical-debt ratio calculation is identical between them.
Should I block merges on debt ratio?
On new code only, yes. The 'Clean as You Code' pattern that SonarQube has promoted since 2020 sets quality gates on new code (debt added in this PR, new code coverage, no new bugs or vulnerabilities). Blocking merges on overall codebase debt is counter-productive because legacy debt is not the PR author's fault and they cannot easily fix it.