Cyclomatic complexity is a count of the linearly independent paths through a piece of code. Thomas McCabe defined it in 1976, and the practical reading is simple: it is roughly one plus the number of decision points — every `if`, `while`, `for`, `case`, `&&`, `||` and `catch` adds one.
Computing it by hand
function shippingCost(order) { // 1 (base path)
if (!order.items.length) return 0; // 2
if (order.isDigital) return 0; // 3
let cost = BASE;
if (order.weight > 10) { // 4
cost += HEAVY_SURCHARGE;
}
if (order.express && order.priority) { // 5, 6 (&& adds one)
cost *= 2;
}
return cost;
}
// Cyclomatic complexity = 6, so at least 6 tests to cover every path.What it is genuinely good for
- Estimating minimum test count. The number is a floor on the paths needing coverage — the most defensible use of the metric.
- Finding candidates for attention. A function at 40 in a codebase averaging 5 is worth a look, without prejudging what you will find.
- Tracking a trend. Rising average complexity in a module over months says something real about its direction.
What it cannot tell you
It measures branching, which is only one contributor to how hard code is to understand:
- A 40-branch `switch` mapping country codes is trivial to read and scores badly.
- A five-line function with a subtle race condition scores well and will ruin a weekend.
- It says nothing about naming, coupling, cohesion, or whether the abstraction makes sense.
- It is blind to the thing that actually costs most: how much of the system you must hold in your head to change this safely.
Goodhart's law applies immediately
Set a complexity threshold as a gate and engineers will meet it — usually by extracting three arbitrary helper functions that each score fine, leaving the same logic spread across four places and harder to follow than before. The metric improves, the codebase does not. Use it to prompt a conversation, never as a pass condition.
A sensible way to use it
- Report it; do not gate on it.
- Look at the outliers relative to your own codebase, not to a number from a textbook.
- Pair it with change frequency — a complex function nobody touches is cheap; a complex function edited weekly is where the defects are.
- Treat a rise in a specific module as a signal to look, not as a verdict.
Cognitive complexity
Several tools now report cognitive complexity, which weights nesting depth more heavily and does not penalise flat `switch` statements. It tracks readability better than the cyclomatic count in most codebases, and is worth preferring where your tooling offers both — with the same caveat about targets.
Frequently Asked Questions
What is a good cyclomatic complexity?
There is no universal number. Common guidance suggests reviewing above 10, but the useful comparison is against the rest of your codebase and the change frequency of the function in question.
Does it apply to generated code?
It computes fine. Its usefulness drops, because generated code tends to be flat and defensively branchy — scoring moderately while still being hard to reason about for entirely different reasons.
Should complexity be in CI?
Reported in CI, yes. Blocking on it produces extraction-for-the-metric's-sake, which makes code worse while making the number better.
References
- Structured Testing: A Testing Methodology Using the Cyclomatic Complexity Metric (NIST SP 500-235) — NIST / Watson & McCabe
- The Agentic Engineering Trends Report 2026 — SaaSRise
About Jishu Labs
Jishu Labs is a software development company founded in 2016. We build custom software, AI/ML systems, and full-stack web and mobile applications for clients, and we make eight AI tools for software teams.