Maximum Complexity
complexity_max — The highest complexity score of any single function
What It Measures
complexity_max is the highest cognitive complexity score of any individual function, method, or class in your repository. It identifies your single most complex piece of code — the one that is hardest to understand, most likely to contain bugs, and most dangerous to modify.
While complexity_avg shows the overall trend, complexity_max reveals the worst-case hotspot. A codebase can have a low average but still contain a few extremely complex functions that are responsible for a disproportionate number of bugs.
Why It Matters
Bug Concentration
The most complex function in your codebase is statistically the most likely to contain defects. Studies show that complexity and defect density have a near-linear correlation — doubling complexity roughly doubles the expected bug count.
Change Risk
Highly complex functions are the riskiest to change. Every modification has a high probability of introducing unintended side effects because the developer cannot hold all the logic paths in their head at once.
Test Difficulty
To achieve full branch coverage on a function with complexity score N, you need at least N+1 test cases. Functions with complexity scores above 25 can require hundreds of tests for full coverage, making thorough testing impractical.
How It's Calculated
The scanner computes a complexity score for every function in every file, then reports the single highest value. The score for each function uses the same cognitive complexity algorithm as complexity_avg — accounting for nesting, branches, loops, logical operators, and exception handling.
Interpreting Values
| Max Score | Assessment | Action |
|---|---|---|
| ≤ 15 | Good — all functions are manageable | Continue monitoring |
| 16 - 30 | Moderate — some functions need attention | Review the flagged function; refactor if it changes often |
| 31 - 50 | High — significant bug risk | Schedule refactoring before next feature touches this code |
| > 50 | Critical — nearly untestable | Decompose immediately; consider this a blocking issue |
When to Use Max vs P95
complexity_max is useful for identifying your single worst function, but it can be misleading for alerting — one generated or legacy function can keep the max permanently high even as the rest of the codebase improves. For threshold-based alerts, complexity_p95 is usually a better choice because it filters out single outliers and reflects the top 5% of functions.
Tackling Your Most Complex Function
1. Identify It
Your dashboard shows which function has the highest complexity score, including its file path and line number. Start there.
2. Understand Why It's Complex
Common patterns: deeply nested if/else chains, long switch statements, multiple loops with conditional logic, error handling wrapped around business logic, or accumulated feature flags.
3. Decompose
Break the function into smaller pieces, each with a clear name and single responsibility:
- Extract validation into a separate function
- Move each branch of a conditional into its own function
- Replace switch statements with strategy objects or lookup tables
- Separate error handling from business logic
4. Verify
Run a new scan after refactoring. Your complexity_max should drop significantly, and complexity_avg should decrease as well since the high outlier is eliminated.
Related Metrics
- complexity_avg — Average complexity; shows the overall trend
- complexity_p95 — 95th percentile; better for alerting than max
- alert_count — Reducing max complexity typically reduces active alerts