Cyclomatic complexity

What is cyclomatic complexity?

Cyclomatic complexity is a software metric, introduced by Thomas McCabe in 1976, that counts the number of linearly independent paths through a piece of code. In practice it starts at 1 for a straight-line function and increases by one for each decision point: every if, else if, loop, case clause, catch, and boolean operator in a condition. A function with complexity 12 has at least 12 distinct paths a test suite would need to exercise. The metric is a proxy for how hard code is to understand and how many ways it can go wrong: humans hold a handful of branches in their head comfortably, and a function with dozens exceeds that budget for everyone, including its author.

How it shows up in real code

Complexity accumulates by accretion. A clean function gains an edge-case if, then a feature flag, then a customer-specific branch, and two years later looks like this:

if (user && (user.plan === "pro" || legacyPro) && !suspended && (region !== "EU" || gdprOk)) { ... }

Static analysis tools (ESLint’s complexity rule, SonarQube, Radon for Python, and most linters) compute the number automatically. Common working thresholds treat 1 to 10 as fine, 11 to 20 as worth attention, and beyond that as a refactoring candidate, though the thresholds are conventions rather than laws.

Why it matters in a code audit

Complexity is where bugs hide and tests give up. Each additional path is a case someone must reason about on every change, and in practice the rare branches are precisely the ones with no test, so an auditor cross-references complexity against test coverage: a complexity-30 function with 40% branch coverage is a defect generator waiting for input. Audits also weight complexity by churn, since a gnarly function nobody touches is cheap, while the same function edited weekly taxes every change. The metric has known blind spots (it undercounts the pain of nesting and cannot see bad naming), so auditors use it to rank candidates for human reading rather than as a verdict. Chronic high complexity is one of the classic code smells, catalogued in code smells every audit flags.

A free code audit pinpoints the handful of functions where complexity is actually costing you.