Documentation Index
Fetch the complete documentation index at: https://mehen.ophi.dev/llms.txt
Use this file to discover all available pages before exploring further.
The Halstead metrics are a suite of measures derived purely from the operators and operands in a
source file. Maurice Halstead proposed them in Elements of Software Science (1977) as a way to
characterize program size, difficulty, effort, and bug count from token statistics alone — without
running the code.
mehen reports the canonical Halstead suite per space and per file.
What mehen emits
| Key | Type | Definition |
|---|
halstead | float | Default surface; equals halstead.volume. |
halstead.volume | float | V = N · log₂(η) |
halstead.difficulty | float | D = (η₁ / 2) · (N₂ / η₂) |
halstead.effort | float | E = D · V |
halstead.vocabulary | int | η = η₁ + η₂ |
halstead.length | int | N = N₁ + N₂ |
halstead.n1 | int | Distinct operators. |
halstead.N1 | int | Total operators. |
halstead.n2 | int | Distinct operands. |
halstead.N2 | int | Total operands. |
halstead.bugs | float | B = V / 3000 (estimated delivered bugs). |
halstead.time | float | T = E / 18 (estimated implementation time, seconds). |
halstead.estimated_program_length | float | Ñ = η₁ · log₂(η₁) + η₂ · log₂(η₂) |
halstead.level | float | L = 1 / D |
halstead.purity_ratio | float | Ñ / N |
Definitions
| Term | Meaning |
|---|
| η₁ | Number of distinct operators in the program. |
| η₂ | Number of distinct operands. |
| N₁ | Total occurrences of operators. |
| N₂ | Total occurrences of operands. |
η = η₁ + η₂ (vocabulary)
N = N₁ + N₂ (length)
V = N · log₂(η) (volume)
D = (η₁ / 2) · (N₂ / η₂) (difficulty)
E = D · V (effort)
B = V / 3000 (estimated bugs)
T = E / 18 (estimated implementation time)
18 in the time formula is Halstead’s “Stroud number” — the number of mental
discriminations per second a programmer is assumed to make.
Per-language operator/operand split
What counts as an operator vs. an operand is language-specific. mehen’s analyzers follow the prevailing
convention:
- Operators: keywords (
if, for, return, …), arithmetic and logical symbols (+, &&, …),
parentheses pair (), brackets [], and assignment operators.
- Operands: identifiers, literal values (numbers, strings, booleans, null/undefined), and type names.
The exact mapping for each language lives in its analyzer crate at crates/mehen-<lang>/.
How to read it
| Halstead | Interpretation |
|---|
volume low, difficulty low | Small, easy code. |
volume high, difficulty low | Long but mechanical (e.g., big lookup table). |
volume low, difficulty high | Compact but tricky (clever one-liner). |
volume high, difficulty high | Large and tricky — refactor candidate. |
halstead.bugs and halstead.time are rough estimates with limited empirical backing. Treat them as
order-of-magnitude signals, not promises.
References
- Halstead, M. H. (1977). Elements of Software Science. Operating and Programming Systems Series.
Elsevier. OSTI record.
- Kearney, J. K., et al. Software Complexity Measurement — MIT lecture notes that summarize the
Halstead operator/operand formulation alongside McCabe.
PDF (MIT OCW 16.355).
- Christensen, K., Fitsos, G. P. & Smith, C. P. (1981). A perspective on software science. IBM
Systems Journal 20(4): 372–387. DOI.
- Sonar: Halstead in the metrics definitions.
- Radon: Halstead — Python
reference implementation of the formulas.
See also
