What is the cognitive complexity limit in EK9?

← Code Quality · Ref: Q765

EK9 measures cognitive complexity — how difficult code is to understand, not just how many paths exist. When it exceeds 35, E11021 triggers.

HOW IT DIFFERS FROM CYCLOMATIC COMPLEXITY

- Cyclomatic: counts decision points (each if/while/for = +1)
- Cognitive: adds penalties for NESTING depth (nested if = +depth, not +1)

NESTING MULTIPLIER

Each nesting level multiplies the cost:
- Level 0: if = +1
- Level 1: nested if = +2
- Level 2: doubly nested if = +3

HOW TO REDUCE COGNITIVE COMPLEXITY

1. Extract nested blocks into helper functions (resets nesting)
2. Use guard expressions to flatten conditional chains
3. Replace complex boolean expressions with named predicates

See Q312 for complexity metrics overview. See Q728 for nesting depth limits.

Example

defines module qa.codequality.cognitiveboundary

  defines function

    checkA()
      -> number as Integer
      <- rtn as Boolean: number > 0

    checkB()
      -> number as Integer
      <- rtn as Boolean: number > 0

    checkC()
      -> number as Integer
      <- rtn as Boolean: number > 0

    <?-
      This function has cognitive complexity near the threshold of 35.
      Each nested level costs more than the last due to the nesting multiplier.
    -?>
    evaluateItems()
      ->
        items as List of Integer
        count as Integer
        enabled as Boolean
      <-
        message as String: "none"

      //Level 1: +1 each
      if checkA(count)
        //Level 2: +2 each
        if checkB(count)
          //Level 3: +3
          if enabled
            //Level 4: for = +4
            for item in items
              //Level 5: +5
              if checkC(item)
                message: "deep-a"
              else
                message: "deep-b"
          else
            message: "no-flag"
        else
          if enabled
            for item in items
              if checkA(item)
                message: "deep-c"
              else
                message: "deep-d"
          else
            message: "low"
      else
        //Level 2: +2 each
        if checkB(count)
          message: "alt-a"
        else
          message: "default"

  defines program

    CognitiveComplexityDemo()
      stdout <- Stdout()
      numbers <- [1, 2, 3]
      stdout.println(evaluateItems(numbers, 5, true))
      stdout.println(evaluateItems(numbers, 0, false))

Common mistakes

E11021 — Adding nested if at depth 6 adds +6 cognitive complexity, pushing the function past the threshold of 35. Each nested level costs +depth. Extract deep logic into helper functions. See ek9 -h E11021 for details.

Incorrect:

        if checkB(count)
          if enabled
            for item in items
              if checkC(item)
                message: "alt-a"
              else
                message: "alt-b"
          else
            message: "alt-low"
        else
          message: "default"

Correct:

        if checkB(count)
          message: "alt-a"
        else
          message: "default"
Other ways to ask this
  • What triggers E11021 excessive cognitive complexity?
  • How does EK9 measure cognitive complexity?
  • What is the difference between cyclomatic and cognitive complexity?
  • Why does EK9 limit how hard code is to understand?

Coming from another language?

Java: SonarQube measures cognitive complexity (advisory, default threshold 15). C#: NDepend measures cognitive complexity (informational). Python: no cognitive complexity in standard tools. EK9: cognitive complexity > 35 is a compiler error.

Keywords: E11021, metric, readability, understanding, threshold, quality, nesting, complexity, cognitive