Code Health: The Complete Guide to Metrics and Scores (2026)

Code health metrics measure how risky a file is to change. The useful ones combine code shape (cyclomatic complexity, nesting depth, function length), coupling, test coverage and git history (churn, ownership, recent bug fixes). repowise rolls 23 of them into a 1-to-10 score per file: 8.5 and above is excellent, below 4.0 is at risk.

Code health metrics at a glance

Four tools publish a headline code quality number, and they answer different questions. The table compares how each defines it, as of October 2026, with each vendor's own documentation linked below.

Sources: SonarQube metric definitions, CodeScene code health docs, Qlty maintainability metrics.

I build repowise, so the deep dive uses its metrics: I can say exactly how each is computed. The definitions carry over to any tool that measures the same things. For a side-by-side of the platforms, see best code health tools in 2026.

What is code health?

Code health is a per-file estimate of how likely a file is to cause bugs and how hard it is to change. repowise computes it from static checks on the parse tree and the dependency graph plus git history. The repo score is the average across files, weighted by lines of code.

The score is deterministic: the same inputs always give the same number, with no model and no LLM anywhere. The 23 markers behind the headline sit inside a wider set of 59 detectors that also drive the maintainability and performance signals. Analysis is budgeted at under 30 seconds for 3,000 files, and a CI test enforces it.

A rolled-up average hides the one file slowing delivery down. Code health puts the reason next to the number, so you can open any file and see which markers lowered its score.

repowise file page for spec.py in its own repository, showing a code health score of 8.3 out of 10 with five open findings and 59 dependents

The code health metrics, defined

These are the metrics that move the headline score, with the thresholds the scorer uses. "Fires" means the metric produces a finding and deducts from the file's score. A healthy file is one where none fire, or only at low severity.

Weights differ because the scorer was calibrated against real bug history. Smells that fire often but predict bugs weakly (low cohesion, long parameter list, DRY violation, error handling) count at reduced weight in the defect score, and in full in maintainability. Brain method and repeated nesting are listed as advisory findings and do not deduct. Co-change scatter, change entropy and ownership risk carry the most weight. The marker tour walks through the full roster.

How metrics become a score

Each file starts at 10 and every finding deducts from it, with a cap per category. The caps stop one kind of problem from dominating:

The result is clamped between 1 and 10. History amplifies code risk and never stands alone: a file whose code has no findings cannot drop below 9.0 from history, so a busy but clean file is read as busy, not broken.

Score bands

The bands are absolute, so a 6 means the same thing in every repository.

Three numbers summarize a repository: average health (line-weighted), hotspot health (the same average over hotspot files only) and the worst performer. Read average health first. A file in an unsupported language is counted as not analysed, never scored as a 10.

The three signals: defect risk, maintainability, performance

repowise keeps three co-equal signals and never blends them into one number. They come from one stream of findings, each with its own weights.

Defect risk is the validated signal, fitted against a defect corpus. Maintainability is set by hand and never fitted to bugs, so long methods, primitive obsession and duplication show up there without diluting the bug signal. The performance scan favors precision over recall: fewer findings, fewer false alarms. All three are deterministic.

How code health differs from a technical debt ratio

A debt ratio counts rule violations on one snapshot; code health weighs git history as heavily as structure. SonarQube Server and Qlty both divide estimated remediation effort by the cost to develop the code, then map the ratio to a letter. It is a tidy number, but it is built from a single snapshot of the code.

Does a code health score predict bugs?

Yes: on a leakage-free benchmark, repowise scores reach ROC AUC 0.74 across 21 open-source repositories and nine languages. We scored each repo at a historical commit, then checked the files against the next six months of bug fixes. Nothing after that commit feeds the score.

Under a fixed review budget of 20% of lines, the score surfaces 2.3x the defects CodeScene does on the same files, and its effort-aware ranking (Popt) is 0.607 on the same corpus. It also beats ranking by recent churn, by +0.10 AUC, and on the external PROMISE jEdit dataset it holds at 0.76 to 0.78.

The gain is in ordering a fixed review budget and saying why. The benchmark is open and reproducible: the full method, confounds and per-repository results are in the validation study, and you can run it on your own repositories. See also why process metrics beat structural metrics.

How to track code health over time

Score every file on each merge and watch the trend, not a single snapshot. repowise stores a snapshot on every init, update and health --recompute (the last 50 per repository) and raises three alerts:

• Declining: the score fell 0.5 or more against five snapshots back.
• Predicted decline: three falls in a row.
• History drag: either of the above, where only the git-history half moved, so there is nothing in the code to act on.

repowise init              # full index; scores every file
repowise health            # fix first, KPIs, lowest-scoring files
repowise health --trend    # the last 10 snapshots
repowise update            # re-scores only the files that changed

To see whether refactoring helped even while its churn raises the history half, read the code-shape view with repowise health --counts code_shape. More on reading the series in spotting declining code health trends.

Using the score

Start with the worst files that also change often. Sort by lowest defect-risk score, filter to high churn or high fan-in, and inspect the top three to five. The score says where; the marker breakdown says why.

repowise health leads with a short ranked "Fix first" list. Each item is one unit of work with the first edit, the expected gain, the effort and the tests that check it:

Fix first (3 of 41 eligible items)
 1. Extract the retry branch from parse_config  now, effort M, +1.4 health
    src/config/loader.py:212
    CCN 47 and nesting 6 in a file changed 19 times this quarter.
    verify: pytest tests/unit/test_loader.py

Then pick the move that fits the file: add tests before touching a fragile hotspot, schedule cleanup for a file that is both complex and volatile, or split a boundary where co-change pressure says the module shape no longer matches reality. Agents get the same data through the get_health MCP tool, one of the ten tools repowise exposes.

To gate pull requests on the same signals, use the PR bot. Coverage reports (LCOV, Cobertura, Clover, JaCoCo, Go coverprofile) feed the coverage markers: repowise coverage add coverage.lcov.

Go deeper

• What is code health? A tour of the markers
• Nested vs cyclomatic complexity
• Inside the code health scorer
• Best code health tools in 2026
• The code health feature page

Last reviewed: October 2026.