cogc - Cognitive Complexity

Overview

The cogc command calculates cognitive complexity for C# methods in a project or directory and reports the top 10 methods ranked by score. Unlike cyclomatic complexity, which counts structural paths, cognitive complexity measures how difficult code is for a human to read and understand. It penalizes nesting depth and control-flow breaks more heavily.

Syntax

nmbl cogc <ProjectFileOrDirectory>

Arguments

ProjectFileOrDirectory - Path to a .csproj file, a project directory, or . for the current directory.

Output

Prints the count of files being analyzed, then displays the top 10 methods ranked by cognitive complexity (highest first) in a fixed-width text table, followed by the total number of methods analyzed.

Analyzing 42 C# file(s)...

Top 10 methods by cognitive complexity:

Method                                                                           Complexity
---------------------------------------------------------------------------------------------
MyNamespace.OrderProcessor.ProcessOrder(Order)                                          31
MyNamespace.ReportGenerator.GenerateReport(int, bool)                                   22

Total methods analyzed: 128

Exit Codes

0 - Success, including when no C# files or methods are found.
1 - The required path argument is missing or an unexpected error occurs.

Examples

Analyze a specific project

nmbl cogc src/MyProject/MyProject.csproj

Calculates cognitive complexity for all methods in the project.

Analyze a directory

nmbl cogc src/Services/

Analyzes all C# files in the Services directory.

Analyze the current directory

nmbl cogc .

Compare with cyclomatic complexity

nmbl cc src/MyProject/MyProject.csproj
nmbl cogc src/MyProject/MyProject.csproj

Running both commands gives a more complete picture of code complexity. A method can have low cyclomatic complexity but high cognitive complexity if it uses deeply nested logic.

Understanding Cognitive Complexity

Cognitive complexity differs from cyclomatic complexity in key ways:

Penalizes nesting — deeply nested code is weighted more heavily than flat code.
Accounts for breaks in linear flow — jumps such as goto, recursion, and break with labels increase the score.
Ignores structures that don’t affect readability — for example, a simple switch with many cases does not inflate the score the way it does in cyclomatic complexity.

Complexity guidelines:

0–5: Very easy to understand
6–10: Easy to understand
11–20: Moderate difficulty
21+: Difficult to understand; consider refactoring

ac - Calculate aggregate complexity
cc - Calculate cyclomatic complexity
loc - Count lines of code
todos - Find TODO comments