How to measure code quality
"Code quality" isn't directly measurable, because it isn't one thing. It's a bundle of separate properties — correctness, maintainability, readability, performance, security — and no single number captures all of them. What tools actually measure are proxies: things that are cheap to compute and correlate reasonably well with the properties you actually care about.
The proxy metrics you'll see most often
- Lines of code (LOC) — the weakest proxy on this list. A large file isn't automatically bad, and a small one isn't automatically good, but LOC is cheap to compute and shows up everywhere as a rough size signal.
- Cyclomatic complexity — a count of independent paths through a function. Correlates with how hard a function is to test and reason about.
- Test coverage — the percentage of code exercised by an automated test suite. Says nothing about whether the tests are actually good, only that the lines were executed at least once.
- Duplication percentage — how much of the codebase is copy-pasted rather than shared. Rising duplication is one of the clearest early signals of a codebase getting harder to change safely.
- Defect density — bugs found per thousand lines of code, usually tracked after the fact from a bug tracker. The most direct proxy for real-world quality, and the hardest one to get before shipping.
- Maintainability index — a composite formula (originally from a 1992 paper, popularized by Microsoft's Visual Studio metrics) that blends complexity, size, and comment ratio into one number, conceptually similar to what REPO-SIGHT's health score does for C++, Python, and Java.
What a single static scan can and can't tell you
A one-time scan gives you a snapshot: the current structural shape of the repository. It cannot tell you whether that shape is improving or getting worse without a second scan later to compare against, and it can't measure defect density at all — that requires real production data a static tool never sees. Static metrics are a leading indicator, not a verdict.
A practical starting point
Don't try to track everything at once. Pick two or three numbers you'll actually look at on a recurring basis — complexity density and max nesting depth are a reasonable starting pair for most codebases — rather than drowning in a dashboard of metrics you'll stop checking after the first week.
How REPO-SIGHT approaches this
Rather than presenting five or six separate numbers and leaving you to weigh them yourself, REPO-SIGHT's health score bundles cyclomatic complexity density, average function length, comment density, TODO density, and max nesting depth into a single weighted A–F grade. See exactly how each component is weighted. You can still see the individual numbers behind the grade in the dashboard — the grade is a starting point, not a replacement for looking closer.