Halstead Maintainability Index
debt(d5/e3/b3/t5)
Closest to 'specialist tool catches it' (d5). The detection_hints list phpmetrics, pdepend, and sonarqube — all specialist static-analysis tools that must be explicitly integrated into a pipeline. Halstead violations don't surface via compiler, default linter, or syntax checks; a developer must run a dedicated metrics tool and configure quality gates to see them.
Closest to 'simple parameterised fix' (e3). The quick_fix is 'Run phpmetrics to see Halstead complexity — high volume or difficulty scores signal functions that are doing too much and should be split.' Splitting a function is a small, localised refactor within one component rather than a single-line patch, but it doesn't span multiple files or require cross-cutting changes, placing it firmly at e3.
Closest to 'localised tax' (b3). The term applies_to all contexts (web, cli, queue-worker), suggesting broad reach in theory, but the practical burden is choosing whether and how to integrate Halstead metrics into a quality gate. Once configured in a tool like SonarQube or phpmetrics, the ongoing cost is limited to periodic review of flagged functions — it doesn't reshape the architecture or slow down most work streams.
Closest to 'notable trap' (t5). The misconception field explicitly states that developers wrongly believe Halstead metrics are purely theoretical and unused in practice, when in fact they underpin the Maintainability Index in Visual Studio, SonarQube, and PHP tools. Additionally, common_mistakes note the trap of optimising metrics by shortening variable names, which lowers vocabulary counts while harming readability — a documented gotcha that many developers eventually learn.
Also Known As
TL;DR
Explanation
The Maintainability Index was developed at Hewlett-Packard and later adopted by Microsoft's Visual Studio. It combines: Lines of Code (volume), Cyclomatic Complexity, and Halstead Volume (derived from the number of distinct operators and operands). A score above 85 indicates highly maintainable code, 65–85 is moderate, below 65 is difficult to maintain. It is a rough heuristic — treat it as a relative indicator rather than an absolute measure.
Common Misconception
Why It Matters
Common Mistakes
- Using Halstead metrics in isolation rather than alongside cyclomatic complexity and lines of code.
- Not including Halstead difficulty in your quality gate — it catches complex expressions that low cyclomatic complexity misses.
- Optimising for Halstead metrics by reducing variable names — shorter names lower vocabulary at the cost of readability.
- Not realising that high Halstead volume often indicates a function that should be split.
Code Examples
// High Halstead volume — many operators and operands in one expression:
function calc($a, $b, $c, $d, $e) {
return (($a + $b) * ($c - $d) / $e) % ($a * $c) + ($b - $e) * $d;
// Complex expression: high vocabulary, difficulty, and effort score
}// Halstead metrics — based on operators and operands in source code
// Definitions:
// η1 = distinct operators (e.g. +, =, if, return)
// η2 = distinct operands (e.g. $total, $price, 0.2)
// N1 = total operator occurrences
// N2 = total operand occurrences
// Calculated metrics:
// Vocabulary η = η1 + η2
// Length N = N1 + N2
// Volume V = N * log2(η) — information content
// Difficulty D = (η1/2) * (N2/η2) — mental effort
// Effort E = D * V — total effort to implement/understand
// Example PHP function:
public function applyDiscount(float $price, float $rate): float {
return $price * (1 - $rate);
}
// Operators: function, float, float, float, return, *, -, () → ~6 distinct
// Operands: $price, $rate, 1 → 3 distinct
// Low volume + difficulty = easy to understand and maintain
// Tool:
$ phpmetrics --report-html=report/ src/
// Reports Halstead metrics per method and class
// High Volume (>1000) or Difficulty (>30) → consider refactoring