Skip to content

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.

8 min read
Illustrative opaque ceramic engineering component and its carefully separated cutaway twin reveal a tiny concealed joint weakness.
On this page

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.

The Metrics Menu

The Metrics MenuCyclomaticIndependent pathsCognitiveReading and nestingChurnChange historyThe analyser and local defect history determine how useful each signal is.
Figure 1. Read a complexity measure together with the change context.

Let's start with what's available, then narrow down to what actually matters.

Cyclomatic Complexity (McCabe, 1976)

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: 4
function 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.

Cognitive Complexity (SonarSource, 2016)

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: 6
function processOrder(order: Order) {
  if (order.isPriority) {                    // +1
    for (const item of order.items) {        // +2 (nesting)
      if (item.requiresApproval) {           // +3 (nesting)
        requestApproval(item);
      }
    }
  }
}

// Cognitive complexity: 4
function 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.

Halstead Metrics (1977)

Based on counting operators and operands. Produces metrics like volume, difficulty, and estimated effort. Mostly academic. I haven't found them useful in practice.

Lines of Code (LOC)

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]

Churn (Change Frequency)

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]

Coupling (Afferent and Efferent)

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 Metrics That Actually Predict Bugs

Based on my own data and published research, here's my ranking:

The Bug Prediction Power Ranking

Rank Metric Predictive Power Why It Works
1 Churn x Complexity Very High Hot, complex code = bugs
2 Number of Authors High More hands = more misunderstanding
3 Cognitive Complexity High Matches human comprehension limits
4 File Size (LOC) Moderate-High Simple proxy for everything
5 Coupling (Efferent) Moderate More dependencies = more failure modes
6 Cyclomatic Complexity Moderate Useful but overrated
7 Code Duplication Moderate Fixes applied in one place, not others
8 Test Coverage (inverse) Low-Moderate Low coverage = undetected bugs

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.

My Contrarian Take: Stop Optimizing for Metrics

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.

Here's what I do instead.

The Hotspot Analysis Framework

The Hotspot Analysis FrameworkFind hotspotsChange historyMeasurecomplexityInspect the codeCheck authorsReview expertisePrioritise andactTests, split orrefactorThe ranking in the article is a diagnostic proposal.
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 months
git 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]

bash
python -m pip install lizard
lizard src/orders/OrderService.ts

Step 3: Plot churn vs. complexity.

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.

Setting Useful Thresholds

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.

Tools Worth Using

  1. CodeClimate. Good SaaS option. Calculates cognitive complexity, duplication, and file length. Integrates with GitHub PRs.
  2. SonarQube/SonarCloud. The enterprise standard. Tracks 30+ metrics. Free for open source.
  3. lizard. Command-line tool that calculates cyclomatic complexity for 20+ languages. No configuration needed.
  4. git-of-theseus. Visualizes how code ages and who wrote what. Great for identifying knowledge silos.
  5. CodeScene. Adam Tornhill's tool for hotspot analysis. Best-in-class for churn-based analysis. Commercial but worth it for large codebases.

The Takeaway

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.

Sources

  1. [1]complexity - ESLint - Pluggable JavaScript Linter · ESLint
  2. [2]Cognitive Complexity, Because Testability != Understandability · SonarSource
  3. [3]Mining Metrics to Predict Component Failures - Microsoft Research · Nachi Nagappan, Thomas Ball and Andreas Zeller / Microsoft Research
  4. [4]Use of Relative Code Churn Measures to Predict System Defect Density - Microsoft Research · Nachiappan Nagappan and Thomas Ball / Microsoft Research
  5. [5]GitHub - terryyin/lizard: A simple code complexity analyser without caring about the C/C++ header files or Java imports, supports most of the popular languages. · Terry Yin and Lizard contributors

Checked against these sources on

Related Articles