Codebase Health Review — Sample
A worked example of reviewing a codebase rather than a team — where changes concentrate, where defects come from, what review latency costs, and which technical debt is actually being paid for.
Markdown. No sign-up, no email.
This is an illustrative example. The system and figures are invented to show the shape of a review that produces a short list of work. Copy the structure; measure your own repository.
The review deliberately measures the codebase, not the people. Every figure comes from version control history and the defect record, both of which already exist.
Codebase health — payments platform#
| Repository | 340,000 lines, 6 years old |
| Team | 11 engineers |
| Period | 12 months of history |
| Source | Version control, pull requests, incident and defect records |
1. Where changes concentrate#
| Module | Share of lines | Share of changes | Share of defects |
|---|---|---|---|
| Settlement | 8% | 31% | 44% |
| Payment capture | 14% | 22% | 19% |
| Reporting | 21% | 9% | 6% |
| Customer records | 17% | 11% | 8% |
| Integrations | 22% | 19% | 17% |
| Everything else | 18% | 8% | 6% |
Settlement is 8% of the code, a third of the changes and nearly half the defects. This is the most useful table in the review and it takes an hour to produce from history.
Reporting is the mirror image: a fifth of the codebase, almost never touched. It is frequently proposed for a rewrite because it is old and unfashionable, and the history says it costs nothing.
2. Inside settlement#
| Files changed in over 60% of settlement changes | 3 |
| Largest file | 4,100 lines |
| Distinct authors in 12 months | 9 |
| Median change size | 210 lines |
| Median review time | 4.5 hours |
| Changes reverted | 11 |
Three files are touched by almost every change in the module. They are where the coupling is, and they are why the median change is 210 lines when the median elsewhere is 40 — a small behavioural change requires edits in three places that must agree.
The 11 reverts are all in these three files.
3. Where defects originate#
Every defect that reached production, classified at its root cause rather than at the line that was changed to fix it.
| Origin | Defects | Share |
|---|---|---|
| Requirement ambiguous or incomplete | 29 | 37% |
| Design did not account for a case | 18 | 23% |
| Implementation error | 14 | 18% |
| Interaction with another change | 11 | 14% |
| External dependency changed behaviour | 6 | 8% |
Sixty per cent originate before any code is written. The team's improvement effort in the period went into test coverage and static analysis, both of which act on the 18%.
The 29 requirement defects share a shape: the requirement covered what should happen and not what should happen in the unusual case. Refund of a partially settled batch. Payment arriving twice. Currency changing between authorisation and capture. Each was discovered by production doing it.
4. Review#
| Median | 90th percentile | |
|---|---|---|
| Change size | 40 lines | 480 lines |
| Time to first review | 3.1 hours | 22 hours |
| Time to merge | 7 hours | 3 days |
| Comments per review | 2 | 9 |
| Correlation with defects | |
|---|---|
| Changes under 100 lines | 1.0 (baseline) |
| Changes 100–400 lines | 2.4× |
| Changes over 400 lines | 5.9× |
Large changes are reviewed less well and produce far more defects. The mechanism is not subtle: reviewer comments per hundred lines fall sharply above about 200 lines, because attention does not scale with diff size.
Twenty-two hours to first review at the 90th percentile has a second effect. An author waiting a day starts something else, and returning to a review comment a day later is a context switch that costs more than the comment saved.
5. Technical debt actually being paid for#
Rather than listing everything imperfect, this section lists only debt with a measurable cost in the period.
| Item | Measured cost |
|---|---|
| Three coupled settlement files | 11 reverts, 210-line median change, 44% of defects |
| No integration test environment | 4 days of the 11-day lead time, per change |
| Two payment gateway clients doing the same thing | Every change made twice; 3 defects from divergence |
| Manual reconciliation step | 6 hours a week, every week |
| Old reporting module | None. Do not touch it. |
The last row exists to be argued with. Reporting looks like the worst code in the repository and it has cost nothing in twelve months. Debt is only debt if it is charging interest.
6. Recommendations#
- Decouple the three settlement files. They carry 44% of defects and every revert. Not a rewrite of settlement — a targeted separation of the three, with the coupling as the measure of success.
- Require a written approach for changes over two days. Five sentences, read by one person. Aimed at the 60% of defects that originate before code exists, which nothing currently addresses.
- Set a review response expectation of four hours. The 22-hour tail is the largest avoidable delay in the pipeline and it costs context, not just time.
- Split changes over 400 lines, or accept them knowingly. Six times the defect rate is not a style preference.
- Consolidate the two gateway clients. Every change is made twice and they have diverged three times.
- Leave the reporting module alone. It is not causing anything.
Notes on using this format#
Measure the code, not the people. Every figure here comes from version control and the defect record. None of it is about who wrote what, and a review that reads as a performance assessment will produce defensive answers and no change.
Classify defects at their origin. The most common improvement — more tests — addresses the 18% that are implementation errors. The 60% that come from requirements and design need a different intervention entirely.
Only list debt that is charging interest. Every codebase has ugly code. The three coupled files cost 44% of defects; the ugly reporting module costs nothing, and treating them as the same kind of problem is how rewrites get proposed.