Cognitive complexity
Also known as: CogC max · CogC avg · CogC
What it is
Cognitive complexity estimates how hard control flow is to read, capturing what cyclomatic complexity misses: nested structures, breaks in control flow, and recursive patterns. Each level of nesting adds a penalty on top of the basic increment for a branching construct. A deeply nested if-inside-while-inside-try scores much higher than three sequential if statements at the same indentation level, even if cyclomatic complexity rates them the same. Java and Kotlin use method-backed evidence; TypeScript artifact analysis imports supported SARIF findings. CogC max is the strongest available finding beneath the selected architecture unit; CogC avg is the mean across its available findings.
Why it matters
Cyclomatic complexity counts paths; cognitive complexity supplies a separate reading-difficulty signal. The two can diverge significantly. A large switch statement with flat cases may score high cyclomatic complexity but moderate cognitive complexity. Nested loops with breaks and continues may produce a stronger cognitive signal even with fewer paths. Reading both tells you whether the outlier is mainly broad branching, difficult nesting, or both.
What a high value usually means
High CogC max means at least one contributor has strong nesting or flow-break pressure. High CogC avg means that signal is spread more broadly instead of sitting in one outlier. Inspect the contributor before deciding whether the complexity is inherent. If the flow is accidental, possible responses include naming conditions, flattening nesting, separating responsibilities, or extracting a clearer decision boundary.
What a low value usually means
Low cognitive complexity is a lower reading-difficulty signal. Low CogC alongside low cyclomatic complexity means both nesting pressure and path count are limited. Low CogC alongside high cyclomatic complexity often means the branching is flatter and more parallel rather than deeply nested.
When not to overinterpret it
Cognitive complexity is based on SonarSource's heuristic and remains a proxy. Some code is intrinsically complex because of the problem it implements. Read CogC alongside CC, class or source-file count, and lines of code. One contributor driving the maximum calls for a different investigation than complexity distributed across the aggregate.
Where AtlasArc shows it
CogC max in the Hotspots bubble chart as an optional Y axis. Both CogC max and CogC avg as heatmap colour overlays on the Topology Graph, Package Matrix, and Composition view. CogC max in the Subsystems bubble chart. CogC max and CogC avg in Metrics for supported packages, classes, source folders, and source files.
How AtlasArc computes it
Cognitive complexity assigns a base increment for each flow-breaking construct (if, else if, else, while, for, do, switch, catch, break, continue, recursion) and additional nesting penalties for each level of nesting depth at the point where the construct appears. Java and Kotlin use AtlasArc.io's SonarSource-compatible implementation; TypeScript values are imported from supported SARIF findings.