low-complexity

Low Complexity Code

Every function/method written or modified MUST target:

• Cognitive Complexity <= 5 (SonarSource metric). Acceptable up to 10 for inherently complex logic. Never exceed 15.
• Cyclomatic Complexity <= 5. Acceptable up to 10. Never exceed 15.

For full scoring rules, see cognitive-complexity-spec.md.

Cognitive Complexity Quick Reference

+1 for each: if, ternary (? :), switch (whole), for, while, do while, catch, else if, else, goto LABEL, break/continue LABEL, each method in a recursion cycle, each sequence of like boolean operators (&& / ||).

+1 nesting penalty on top of structural increment for: if, ternary, switch, for, while, catch — when nested inside another flow-break structure.

Free (no increment): method calls, try, finally, case labels, null-coalescing (?., ??), early return, simple break/continue, lambdas (but lambdas increase nesting level).

Cyclomatic Complexity Quick Reference

+1 for the method entry, +1 for each: if, else if, for, while, do while, case, catch, &&, ||, ternary ?. Core definition; some analyzers may vary by language.

Mandatory Reduction Techniques

Apply these in order of preference:

1. Extract method/function — Move a coherent block into a named function. Resets nesting to 0. First choice when the extracted block forms a coherent unit.
2. Early return / guard clause — Invert condition, return early, reduce nesting by 1 level.
3. Replace nested conditions with flat logic — if A { if B { becomes if A && B { (saves nesting penalty).
4. Replace if/else chains with polymorphism, strategy pattern, or lookup table — Eliminates branching entirely.
5. Replace loop + condition with declarative pipeline — filter/map/reduce or LINQ or streams instead of for + if.
6. Decompose boolean expressions — Extract complex conditions into named boolean variables or predicate functions.
7. Replace flag variables with early exit — Eliminate boolean flags that control flow later.
8. Use language idioms — Null-coalescing, optional chaining, pattern matching, destructuring. These are often lower-cost than equivalent if/else chains (destructuring is free; pattern matching is +1 for the whole match vs +1 per branch in if/else).

How to Apply

When writing any function/method:

1. Write the logic
2. Mentally count: each if/else if/else/for/while/switch/catch/ternary = +1, each nesting level on structural ones = +1 more, each boolean operator sequence = +1
3. If score > 5, refactor using the techniques above before finalizing
4. Prefer multiple small functions over one large function
5. Nesting depth > 2 is a smell — extract immediately

Bad vs Good Examples

Bad: Nested conditionals (CogC = 9)

def process(user, order):
    if user.is_active:                    # +1
        if order.is_valid:                # +2 (nesting=1)
            if order.total > 100:         # +3 (nesting=2)
                apply_discount(order)
            else:                         # +1
                charge_full(order)
        else:                             # +1
            raise InvalidOrder()
    else:                                 # +1
        raise InactiveUser()              # Total: 1+2+3+1+1+1 = 9

Good: Guard clauses + extraction (process CogC=2, charge CogC=2)

def process(user, order):               # CogC = 2
    if not user.is_active:                # +1
        raise InactiveUser()
    if not order.is_valid:                # +1
        raise InvalidOrder()
    charge(order)

def charge(order):                       # CogC = 2
    if order.total > 100:                 # +1
        apply_discount(order)
    else:                                 # +1
        charge_full(order)

Bad: Loop with nested conditions (CogC = 10)

function findFirst(items, criteria) {
  for (const item of items) {              // +1
    if (item.active) {                     // +2 (nesting=1)
      if (item.type === criteria.type) {   // +3 (nesting=2)
        if (item.score > criteria.min) {   // +4 (nesting=3)
          return item;
        }
      }
    }
  }                                        // Total: 1+2+3+4 = 10
  return null;
}

Good: Flat filter + early continue (findFirst CogC=5, matches CogC=1)

function findFirst(items, criteria) {      // CogC = 5
  for (const item of items) {              // +1
    if (!item.active) continue;            // +2 (nesting=1)
    if (matches(item, criteria)) return item; // +2 (nesting=1)
  }
  return null;
}

function matches(item, criteria) {         // CogC = 1
  return item.type === criteria.type       // +1 (&& sequence)
    && item.score > criteria.min;
}