Cyclomatic Complexity Explained (With Real Thresholds)

Cyclomatic complexity is the oldest and still most widely reported code complexity metric: a count of how many independent paths run through a function's logic. It's cheap to compute, easy to explain in a code review comment, and - on its own - a surprisingly weak predictor of whether a given function is actually hard to work with. Understanding what the number does and doesn't tell you matters more than memorizing the formula.

The metric predates most of the languages it's now measured in. McCabe was working with FORTRAN control-flow graphs in 1976, and the underlying idea - a function's branch count maps to how many tests you need to exercise every path - has survived essentially unchanged into every modern linter's complexity rule.

Cyclomatic complexity answers "how many tests does this need?" It was never built to answer "how hard is this to read?" - and treating it as if it does is where most teams go wrong with the number.

How Is Cyclomatic Complexity Calculated?

The formal definition comes from graph theory: M = E - N + 2P, where E is the number of edges in the control-flow graph, N the number of nodes, and P the number of connected components (almost always 1 for a single function). In practice, no tool builds an explicit graph anymore - they walk the abstract syntax tree and increment a counter for every decision point: if, else if, for, while, case, ternary expressions, and boolean operators (&&, ||) inside a condition. A function with zero branches starts at 1; each additional decision point adds one.

Why Does It Matter, and Where Does It Fall Short?

Two findings, replicated across decades of empirical software-engineering research, keep cyclomatic complexity relevant despite its age. First, it correlates with defect density: more independent paths generally means more paths nobody wrote a test for, and untested paths are where bugs live. Second, it correlates with modification time: a reviewer or a future maintainer takes measurably longer to safely change a function with twenty branches than one with three.

The correlation is real but loose, and that looseness is the metric's main weakness. A long, flat function with ten sequential if statements that each handle one independent case can score as "complex" while reading easily top to bottom, because each branch is simple and there's no nesting to track. A short function with three deeply nested conditionals can score lower while being genuinely hard to follow, because nesting depth - not raw branch count - is what actually taxes a human reader's working memory. Cyclomatic complexity was designed to answer "how many tests does this need," and it does that reasonably well. It was never designed to answer "how hard is this to read," which is the gap cognitive complexity was built to close.

Where Does CodePulse Fit?

CodePulse doesn't parse function bodies or compute a cyclomatic complexity score - that's squarely a static-analysis job, and tools built for it (SonarQube, CodeClimate, language-specific linters) do it well. What CodePulse tracks from the same GitHub history is the signal that tells you where to point that tooling first: which files change constantly, how concentrated ownership is, and how much churn a file absorbs release after release. High-complexity code and high-churn, single-owner code overlap often enough that the two views are worth running side by side.

A complexity score tells you a function is hard to test. Change history tells you whether anyone's actually paying that cost yet.

For the readability half of this picture, see our cognitive complexity guide. For the broader discipline both metrics feed into, see what quality engineering actually covers or our bus factor and knowledge silo guide for the ownership-concentration angle on the same risky files.

If you want to see your own file hotspots before deciding what to refactor, start a free CodePulse trial. It reads directly from your GitHub history, so there's nothing to configure before you see real numbers.