← Back to glossary

Code Readability Metrics

quality Intermediate

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