← Back to glossary

Code Readability Metrics

Code Quality Intermediate

debt(d5/e5/b3/t5)

d5 Detectability Operational debt — how invisible misuse is to your safety net

Closest to 'specialist tool catches' (d5), since PHPMD/phploc/SonarQube/CodeClimate are dedicated metrics tools that flag CC/LOC/params thresholds — not default linters.

e5 Effort Remediation debt — work required to fix once spotted

Closest to 'touches multiple files / significant refactor in one component' (e5), because remediating poor readability metrics typically means refactoring multiple functions/classes flagged by the tool, not a one-line swap.

b3 Burden Structural debt — long-term weight of choosing wrong

Closest to 'localised tax' (b3), since adopting metrics rules in CI imposes ongoing review/refactor pressure but doesn't shape system architecture; applies_to spans web/cli/queue but only at the policy layer.

t5 Trap Cognitive debt — how counter-intuitive correct behaviour is

Closest to 'notable trap' (t5), matching the misconception that low metrics guarantee readability — a documented gotcha (Goodhart's law on metrics) that teams learn through experience of gaming CC.

About DEBT scoring → scored by claude-opus-4-7 · 2026-05-11 · reviewed by human

TL;DR

Readability can be measured — cyclomatic complexity, cognitive complexity (SonarQube), lines per function, parameter count, and nesting depth are all quantifiable proxies for readability.

Explanation

Key metrics: Cyclomatic Complexity (CC) — control flow paths. Cognitive Complexity (CC2, SonarQube) — mental effort to understand, penalises nesting more than CC. Lines of Code per function (LOC) — under 20 is ideal. Parameter count — under 4 parameters. Nesting depth — under 3 levels. Halstead metrics — volume, difficulty, effort. Maintainability Index (0–100, VS Code, Visual Studio) — composite metric. Tools: PHPStan (complexity), PHPMD, SonarQube, CodeClimate, phploc (PHP Lines of Code). These are guides, not absolute rules — context matters.

Common Misconception

✗ Low metrics always mean readable code — a function with low complexity but cryptic variable names is still unreadable. Metrics are proxies, not guarantees.

Why It Matters

Measurable metrics enable objective code review discussions and track codebase health over time — preventing the gradual degradation of readability.

Common Mistakes

Optimising for metrics rather than readability — gaming CC by moving code into helper functions that don't improve clarity.
Treating metrics as hard limits rather than signals for review.
Not setting baseline metrics for a codebase and tracking change over time.

Code Examples

✗ Vulnerable

// High CC, high nesting, short but unreadable:
function p($u,$a){if($u&&$a){if($u->r>0){if($a<100){return $u->r*$a;}}}return 0;}

✓ Fixed

function calculateDiscount(User $user, float $orderAmount): float {
    if (!$user || $orderAmount <= 0) return 0.0;
    if (!$user->hasActiveDiscount()) return 0.0;
    return $user->discountRate * $orderAmount;
}

References

https://phpmd.org/rules/codesize.html