Code metrics
A metric is an instrument, not a judge. Cyclomatic complexity, churn, and
coverage each measure one narrow thing, and treating any as a target invites
gaming: developers split functions to dodge a threshold without making the code
clearer. Used well, metrics answer "where do I look first?" across code too
large to read. Used badly, they become a quota that punishes honest code.
Method
- Rank hotspots by churn times complexity, not either alone. A complex file
nobody edits is dormant; a simple file edited daily is fine. The product
finds files that are both hard to grasp and constantly changing.
code-maat
and git-of-theseus compute this from git history.
- Read complexity as a prompt to inspect, then open the file. A cyclomatic
score of 30 from
radon, lizard, or gocyclo means "go read this," not
"this is broken." Some dense functions are correct; some tiny ones hide bugs.
- Trend metrics over time, not against an absolute. Track whether a
module's complexity and churn rise or fall release over release. Direction
of travel tells you more than a snapshot measured against an arbitrary bar.
- Never gate a merge on a single number. A hard "coverage must be 80%"
rewards tests of trivial getters and punishes hard-to-test glue. Let metrics
flag code for review, and let a person make the call.
- Cross-check metrics against defect and incident history. Overlay the
files that show up in bug fixes and postmortems onto your hotspot list.
Where they agree you have a real target; where a metric fires alone, stay
skeptical.
- Report with context, never as a leaderboard. Say "these three files are
high-churn, high-complexity, and appear in recent incidents" rather than
ranking authors or files by score. The number opens a conversation, not
closes it.
Litmus tests
- For any flagged file, can you explain in words why it deserves attention?
- Would the metric survive being made a target, or get gamed within a sprint?
- Do the files it flags overlap with the files that actually cause incidents?
Boundaries
Metrics inform prioritization; they do not settle correctness or design quality,
which need a person reading the code. Defer thresholds to team agreement, and
remember that a codebase's real problems, bad abstractions and unclear
ownership, often leave no numeric trace at all.
1---2name: code-metrics3description: Read code metrics as smoke that points at where to look, not as verdicts that rank code good or bad. Use when triaging a large codebase for refactoring targets or reviewing metric-gated quality checks.4---56# Code metrics78A metric is an instrument, not a judge. Cyclomatic complexity, churn, and9coverage each measure one narrow thing, and treating any as a target invites10gaming: developers split functions to dodge a threshold without making the code11clearer. Used well, metrics answer "where do I look first?" across code too12large to read. Used badly, they become a quota that punishes honest code.1314## Method15161. **Rank hotspots by churn times complexity, not either alone.** A complex file17 nobody edits is dormant; a simple file edited daily is fine. The product18 finds files that are both hard to grasp and constantly changing. `code-maat`19 and `git-of-theseus` compute this from git history.202. **Read complexity as a prompt to inspect, then open the file.** A cyclomatic21 score of 30 from `radon`, `lizard`, or `gocyclo` means "go read this," not22 "this is broken." Some dense functions are correct; some tiny ones hide bugs.233. **Trend metrics over time, not against an absolute.** Track whether a24 module's complexity and churn rise or fall release over release. Direction25 of travel tells you more than a snapshot measured against an arbitrary bar.264. **Never gate a merge on a single number.** A hard "coverage must be 80%"27 rewards tests of trivial getters and punishes hard-to-test glue. Let metrics28 flag code for review, and let a person make the call.295. **Cross-check metrics against defect and incident history.** Overlay the30 files that show up in bug fixes and postmortems onto your hotspot list.31 Where they agree you have a real target; where a metric fires alone, stay32 skeptical.336. **Report with context, never as a leaderboard.** Say "these three files are34 high-churn, high-complexity, and appear in recent incidents" rather than35 ranking authors or files by score. The number opens a conversation, not36 closes it.3738## Litmus tests3940- For any flagged file, can you explain in words why it deserves attention?41- Would the metric survive being made a target, or get gamed within a sprint?42- Do the files it flags overlap with the files that actually cause incidents?4344## Boundaries4546Metrics inform prioritization; they do not settle correctness or design quality,47which need a person reading the code. Defer thresholds to team agreement, and48remember that a codebase's real problems, bad abstractions and unclear49ownership, often leave no numeric trace at all.
Amey-Thakur