Code Complexity Metrics: Which Ones Actually Predict Bugs
Compare code complexity metrics with churn and ownership, correct common counting mistakes, and use hotspot analysis to choose changes worth investigating next.
For three years, I tracked every production incident at a mid-size SaaS company and correlated them back to code metrics. I expected cyclomatic complexity to be the top predictor. It wasn't even in the top three.
The thing most teams get wrong about complexity metrics is treating them as absolute measures. A function with cyclomatic complexity of 15 isn't inherently buggy. A function with a complexity of 3 that's been modified by 12 different developers in 6 months? That's where your bugs live.
Counts independent paths through a function, starting at 1. Branches and loops add paths, but a plain else does not add another decision. Exact rules, including logical operators and switch variants, depend on the analyser.[1]
typescript
// Cyclomatic complexity: 4function processPayment(payment: Payment): Result { if (!payment.amount) return { error: "No amount" }; // +1 if (payment.amount < 0) return { error: "Negative" }; // +1 if (payment.currency !== "USD") { // +1 payment = convertCurrency(payment); } return chargeCard(payment);}
The problem: Cyclomatic complexity treats all branches as equal. A 10-branch switch statement that maps enum values to strings has the same complexity as a 10-branch nested if-else tree with side effects. One is trivial. The other is a bug factory.
Designed to fix cyclomatic complexity's shortcomings. It penalizes nesting, recognizes that some structures are harder to understand than others, and ignores shorthand patterns.[2]
typescript
// Cognitive complexity: 6function processOrder(order: Order) { if (order.isPriority) { // +1 for (const item of order.items) { // +2 (nesting) if (item.requiresApproval) { // +3 (nesting) requestApproval(item); } } }}// Cognitive complexity: 4function processOrder(order: Order) { if (!order.isPriority) return; // +1 for (const item of order.items) { // +1 if (item.requiresApproval) { // +2 (inside the loop) requestApproval(item); } }}
Same logic, different complexity scores. Cognitive complexity rewards the early-return pattern, which matches how humans actually read code.
Based on counting operators and operands. Produces metrics like volume, difficulty, and estimated effort. Mostly academic. I haven't found them useful in practice.
The simplest metric. And surprisingly predictive. A 2005 study by Nagappan, Ball and Zeller examined five Microsoft systems and found that no single set of complexity metrics was a universally best defect predictor. Treat file size as an initial proxy and test its usefulness against the local defect history.[3]
How often a file or function changes. This is a process metric, not a code metric, and that's exactly why it works. High churn means the code is either unstable (bugs keep getting found) or under active development (bugs keep getting introduced).[4]
Afferent coupling: how many other modules depend on this one. Efferent coupling: how many modules this one depends on. High afferent coupling means a change here breaks many things. High efferent coupling means changes in many places could break this module.
The first row in this article's ranking combines churn and complexity. The labels are a proposed diagnostic ordering, not measured predictive accuracy for every codebase. This concept comes from Adam Tornhill's work in "Your Code as a Crime Scene." The hotspot analysis guide gives the investigation steps. The idea is simple: code that's both complex and frequently changed is where bugs congregate.
Complex code with little activity can rank lower on a change-based heuristic while still carrying security or operational risk. Compare complexity with change frequency, then investigate the files where both are high.
I was wrong for years about how to use these metrics. I'd set up SonarQube, configure quality gates, and block PRs that exceeded complexity thresholds. The result? Developers gamed the metrics. They'd split one complex function into three functions that called each other, reducing cyclomatic complexity while making the code harder to understand.
Metrics are diagnostic tools, not targets. The moment you make a metric a target, it ceases to be a good metric. This is Goodhart's Law, and it applies to code quality just as much as it applies to economics.
Figure 2. Investigate the signal before choosing the remediation.
Use this analysis as a recurring diagnostic within the codebase understanding process. The time it takes depends on the repository and available tooling.
Step 1: Find your hotspots.
bash
# Get the 20 most frequently changed files in the last 6 monthsgit log --since="6 months ago" --pretty=format: --name-only | \ sed '/^[[:space:]]*$/d' | sort | uniq -c | sort -rn | head -20
Step 2: Measure complexity for each hotspot.
Use your tool of choice. For TypeScript, I like ts-complex. For general use, lizard supports 20+ languages. Lizard is distributed as a Python package.[5]
You don't need a fancy tool. A spreadsheet works. Put churn on the X axis and complexity on the Y axis. The files in the upper-right quadrant are your highest-priority targets for refactoring.
Step 4: Check the author count.
Read the code ownership guide alongside this count to check how expertise is shared and reviews are assigned.
bash
# How many different authors have touched this file?git log --format="%aN" src/orders/OrderService.ts | sort -u | wc -l
Files with high churn, high complexity, and many authors are the most dangerous. They're where miscommunication and conflicting assumptions turn into bugs.
Step 5: Prioritize and act.
Don't try to fix everything. Pick the top 3 hotspots. For each one, decide: refactor, add tests, or split into smaller modules. Make it a sprint goal, not a side project.
If you want guidelines (not rules), here's what I've found reasonable:
Metric
Green
Yellow
Red
Cognitive Complexity
< 15
15-25
> 25
Function LOC
< 50
50-100
> 100
File LOC
< 300
300-600
> 600
Monthly Churn (commits)
< 5
5-15
> 15
Number of Authors (6mo)
< 3
3-5
> 5
Efferent Coupling
< 5
5-10
> 10
These aren't universal truths. A 200-line React component might be perfectly readable. A 50-line cryptography function might be incomprehensible. Context matters more than thresholds.
Stop chasing a single complexity number. Start thinking about code complexity as a function of three variables: inherent complexity of the code, rate of change, and number of people changing it. The intersection of all three is where your bugs live, and that's where your attention should go.
Measure, diagnose, act. In that order.
Frequently asked questions
How is cognitive complexity different from cyclomatic complexity?
Cyclomatic complexity counts independent execution paths. Cognitive complexity also accounts for how control flow is nested and how difficult it is to follow. Check the analyser's rules before comparing scores.
Which complexity metric is the best bug predictor?
The cited Microsoft study found no universally best set of complexity measures across its projects. Use the article's ranking as a diagnostic starting point, then compare its signals with your own defect history.
Can lines of code stand in for complexity?
File size can help with an initial scan, but it does not show how control flow or responsibilities are structured. Inspect the candidate file and add change-history evidence before deciding that it needs remediation.
How do I run Lizard on a TypeScript file?
Install the Python package with pip, then run the lizard command against the file or source directory. Lizard supports TypeScript and reports cyclomatic complexity. Review parser limitations for unusual syntax.
Most code quality dashboards fail because they track too many metrics and live outside the team's workflow. Here are exactly 7 metrics and a 3-week adoption plan that actually works.
Compare cyclomatic and cognitive code complexity with change risk. Check corrected examples, understand each measure’s limits and target refactoring effort.
Set up continuous code quality monitoring with CI gates, trend metrics and alerts. Establish a baseline, define thresholds and review changes with your team.
Code churn reveals more about team health than any code quality score. Learn to distinguish healthy churn from warning signs using the CHURN framework.
Choose static analysis tools for types, security data flow and architecture rules. Follow a staged setup and tune findings against your team’s actual defects.