Reduce Cognitive Complexity

Refactor functions to reduce cognitive complexity score while maintaining identical behavior.

Usage

/complexity [file:function]

Examples:

/complexity # Analyze current diff /complexity services/analyst/core/query.py # Analyze specific file /complexity query.py:process_result # Analyze specific function

Understanding Cognitive Complexity

What increments complexity (+1 each):

• Control flow: if , else if , else , ternary operators

• Loops: for , foreach , while , do while

• Exception handling: catch

• Switch statements: switch , case

• Jump statements: goto , break , continue (labeled)

• Binary logical operators: && , || in conditions

• Recursive function calls

Nesting multiplier:

• Each nesting level adds +1 to structures nested inside

• Deeper nesting = harder to understand

What's free (no increment):

• Function/method calls (encourages extraction)

• Simple return statements

Target: Keep cognitive complexity under 15 per function

Refactoring Strategies

1. Return Early (Reduce Nesting)

Before: Complexity 6

def calculate(data): if data is not None: # +1 total = 0 for item in data: # +1 +1 (nested) if item > 0: # +1 +2 (nested) total += item * 2 return total

After: Complexity 4

def calculate(data): if data is None: # +1 return None total = 0 for item in data: # +1 if item > 0: # +1 +1 (nested) total += item * 2 return total

2. Extract Complex Conditions

Before: Complexity 5

def process_eligible_users(users): for user in users: # +1 if ((user.is_active and # +1 +1 +1 +1 user.has_profile) or user.age > 18): user.process()

After: Complexity 3

def process_eligible_users(users): for user in users: # +1 if is_eligible_user(user): # +1 +1 user.process()

def is_eligible_user(user): return (user.is_active and user.has_profile) or user.age > 18

3. Break Down Large Functions

Extract logical blocks into separate functions with single responsibilities.

Process

Analyze the target function:

• Current complexity score

• What's contributing to it

• Deeply nested structures (2+ levels)

• Complex boolean conditions

Preserve existing tests - understand coverage before changes

Refactor using strategies above:

• Start with early returns to flatten nesting

• Extract complex conditions into named helpers

• Break down into smaller functions if still above target

• Use clear, descriptive names

Verify behavior - run existing tests

Add tests if needed - for new helper functions with complex logic

Critical Requirements

• ✅ Maintain identical behavior

• ✅ Follow existing code patterns

• ✅ Use descriptive names for extracted functions

• ✅ Keep complexity under 15 per function

• ✅ Run tests to verify correctness