Understandability measures how hard it is for a human to follow a method’s control flow. It implements Sonar Cognitive Complexity as described in SonarSource’s 2023 white paper (Cognitive Complexity: a new way of measuring understandability, v1.7).
This metric is separate from this tool’s weighted Cognitive Complexity score, which sums logarithmic weights over structural metrics (lines, arguments, if count, and so on). Understandability follows Sonar’s rule-based control-flow model instead.
Cyclomatic complexity counts paths through code but treats structures like switch and nested loops similarly even when one is much harder to read. Sonar Cognitive Complexity is designed to better match maintainer intuition: it penalizes nested flow breaks, treats switch as a single decision, and ignores method calls that shorthand logic.
Per method, the score follows three rules from the Sonar spec:
- Ignore shorthand — method calls and null-coalescing are not counted.
- Increment for flow breaks — loops,
if, ternary,catch,switch/match, logical-operator sequences, recursion, and multi-levelbreak/continue/goto. - Increment for nesting — each nested flow-breaking structure adds its current nesting depth to the score.
Increments fall into four categories (each adds to the total, but categories clarify nesting behavior):
| Category | Examples |
|---|---|
| Structural | if, loops, ternary, catch, switch |
| Hybrid | elseif, else (no nesting penalty, but increase nesting level) |
| Fundamental | Logical-operator sequences, recursion, jumps |
| Nesting | Extra points when structures are nested |
Structural increments use 1 + nestingLevel; hybrid increments add 1 only.
| Score | Risk |
|---|---|
| 0–5 | low |
| 6–10 | medium |
| 11–15 | high |
| 16+ | very high |
Console output shows score (risk), for example 7 (medium).
Understandability is off by default. Enable it in phpcca.yaml:
cognitive:
showUnderstandability: trueWhen enabled, an Understandability column appears in console output. It does not affect baselines, file reports, or sorting unless those features are extended separately.
- Low (≤5) — easy to follow; usually fine as-is.
- Medium (6–10) — worth a closer look during review.
- High / very high (≥11) — nested or branching logic is taxing; consider extracting methods or simplifying control flow.
Use as an indicator, not an absolute rule. Domain logic, parsers, and constructors may legitimately score higher.