Cognitive Complexity

What It Measures

Cognitive complexity evaluates code from a developer's perspective, accounting for:

• Nested structures: Deeply nested code is harder to follow than flat code
• Control flow breaks: break, continue, and goto statements interrupt mental flow
• Boolean operators: Complex conditions with multiple && and || require more mental tracking
• Recursion: Recursive calls add cognitive overhead

The key insight is that a function with 10 decision points arranged linearly is easier to understand than one with 5 deeply nested decisions.

How It's Calculated

Stellarion calculates cognitive complexity using weighted scoring:

1. Base increment (+1) for each:
   • if, else if, else
   • switch, for, while, do-while
   • catch, try with resources
   • &&, || operators (sequences count as one)
   • Ternary operators
2. Nesting penalty (+1 per level) for structures nested inside:
   • Conditionals
   • Loops
   • Exception handlers
   • Nested functions/lambdas

Severity Classification

Stellarion uses these thresholds to classify cognitive complexity:

Why It Matters

High cognitive complexity leads to:

• More bugs: Developers misunderstand complex code and introduce errors
• Slower development: Code reviews take longer, onboarding new developers is harder
• Maintenance burden: Changes become risky because side effects are hard to predict
• Testing gaps: Complex code paths are often missed in testing

How to Reduce Cognitive Complexity

1. Use Guard Clauses

Replace nested conditionals with early returns:

// Before (Cognitive: 4)
function process(data) {
  if (data) {
    if (data.isValid) {
      return transform(data);
    }
  }
  return null;
}

// After (Cognitive: 2)
function process(data) {
  if (!data) return null;
  if (!data.isValid) return null;
  return transform(data);
}

2. Extract Complex Conditions

Name your boolean expressions:

// Before
if (user.age >= 18 && user.hasLicense && !user.isSuspended) { ... }

// After
const canDrive = user.age >= 18 && user.hasLicense && !user.isSuspended;
if (canDrive) { ... }

3. Decompose Nested Loops

Extract inner loops into separate functions with meaningful names.

4. Flatten Control Flow

Use early returns, switch statements, or lookup tables instead of nested if-else chains.

Relationship to Other Metrics

Cognitive complexity often correlates with but differs from cyclomatic complexity. A function with CC=10 but deep nesting may have cognitive complexity of 25. Stellarion reports both metrics because they capture different aspects of code quality.

For the complete metrics reference, see Stellarion Quality Metrics.