I need to tell you something about cyclomatic complexity: it's lying to you. Not maliciously. It's answering a question you didn't ask.
Cyclomatic complexity was designed in 1976 by Thomas McCabe to estimate the number of test cases needed to cover a function. The count depends on the language and analyser. Branches and short-circuit operators can add paths, while a plain else does not independently add another decision. It's a testing metric masquerading as a readability metric, and the entire industry has been treating them as the same thing for decades.
I've seen functions with a cyclomatic complexity of 4 that took me 20 minutes to understand, and functions with a cyclomatic complexity of 15 that I grasped in 30 seconds. The number wasn't wrong. It was measuring the wrong thing.
The code intelligence guide places complexity alongside other evidence about a codebase. Compare each measure with the question you need it to answer.
# Cyclomatic Complexity: The OG
Both functions have cyclomatic complexity 5 under the stated JavaScript counting rules. The flat version preserves the original behaviour while reducing the nesting contribution to cognitive complexity from 6 to 4. Inspect the implementation as well as the score when assessing readability.
# When cognitive complexity is useful:
- Measuring readability and understandability
- Identifying functions that are hard for new team members to grasp
- Guiding refactoring decisions toward genuinely simpler code, not just fewer test paths
# When cognitive complexity falls short:
- It doesn't account for domain complexity. A function that implements a complex business rule will have high cognitive complexity even if the code is the clearest possible expression of that rule.
- It's language-specific. The SonarSource implementation handles Java and TypeScript well but may not account for language-specific idioms in other ecosystems.
# Change Complexity: The Missing Metric
Here's the one nobody talks about, and it's the most useful in practice.
Assess change risk by tracing what a modification could affect. Use dependency mapping for the structural relationships and hotspot analysis to identify frequently changed areas.
Change complexity isn't a formal metric with a formula. It's a composite score derived from:
- Coupling breadth: How many other files/modules are affected when this code changes?
- Test coverage: What percentage of this code's behavior is verified by tests?
- Historical defect rate: How often do changes to this file introduce bugs?
- Author diversity: How many different developers have successfully modified this code?
I calculate change complexity with a formula like this:
Change Complexity = (Coupling Breadth * 0.3) +
((100 - Test Coverage) * 0.3) +
(Defect Rate * 0.25) +
((1 / Author Count) * 0.15)
This is a proposed local heuristic. Define the input scales, handle an author count of zero and validate the weights before comparing scores. The principle is that a function might be easy to read (low cognitive complexity) and easy to test (low cyclomatic complexity) but extremely dangerous to change because it's coupled to 15 other modules, has 40% test coverage, and only one person has ever modified it successfully.
# A real example
We had a billing calculation function at a previous company. Cyclomatic complexity: 8. Cognitive complexity: 6. By any standard metric, it was fine. Clean code.
But its change complexity was off the charts. It was imported by 23 other modules. It had no integration tests (only unit tests with mocked dependencies). And in the last 12 months, 4 out of 6 changes to it had caused production incidents.
The function was easy to read and easy to test in isolation. It was nearly impossible to change safely. Only change complexity captured that reality.
# The Framework: CCC Assessment
When evaluating a module's complexity, I run all three analyses:
Cyclomatic (Can I test it?): If CC > 15, the function has too many branches. Extract some paths into separate functions.
Cognitive (Can I read it?): If cognitive complexity > 10, the function is hard to understand. Reduce nesting, use early returns, extract sub-expressions into named variables.
Change (Can I modify it safely?): If change complexity is high, the function is risky regardless of how clean it looks. Increase test coverage, reduce coupling, spread knowledge across the team.
The three metrics together give you a complete picture. Any one alone is misleading.
# The Contrarian Take: Complex Code Isn't the Problem. Changing Complex Code Is.
Teams spend enormous effort reducing complexity scores. They refactor, they extract, they simplify. And that's often the right call. But I've seen teams burn weeks refactoring code that doesn't change.
If a function has a cyclomatic complexity of 35 but hasn't been modified in 2 years and has full test coverage, leave it alone. Your refactoring effort is better spent on the function with a complexity of 12 that changes every sprint and keeps breaking things.[3]
Complexity itself doesn't cause bugs. Changing complexity causes bugs. Focus your refactoring budget on the intersection of complexity and churn. That's where the bugs live.
- ESLint
complexity rule: Cyclomatic complexity for JavaScript/TypeScript
- SonarQube / SonarCloud: Both cyclomatic and cognitive complexity with trend tracking
- Qlty: Code smells, metrics and coverage tooling from the makers of Code Climate
- Custom scripts + git log: Change complexity (you'll need to build this yourself, but it's worth it)
Qlty documents code metrics and coverage. Inspect the definitions of the measures your tool reports, then combine them with the local evidence needed to assess a proposed change.[4]