gocognit

Cognitive complexity measures how intuitively hard code is to understand. Unlike cyclomatic complexity, it penalizes nesting and specific control structures more heavily.

Increments

An increment is added for each of the following:

1. if, else if, else
2. switch, select
3. for
4. goto LABEL, break LABEL, continue LABEL
5. Sequence of binary logical operators
6. Each method in a recursion cycle

Nesting

Certain structures increase the nesting level, which in turn increases the weight of subsequent increments:

• Nesting level increases for: if, else if, else, switch, select, for, and function literals/lambdas.
• Nesting increments apply to: if, switch, select, and for structures based on their depth.

The gocognit tool calculates the cognitive complexity of functions and methods in Go source code. You can pass Go files or directories as arguments.

Common Usage Examples

• Analyze the current directory: gocognit .
• Analyze a specific file: gocognit main.go
• Show the top 10 most complex functions: gocognit -top 10 src/
• Show only functions with complexity greater than 25: gocognit -over 25 docker (returns exit code 1 if matches are found)
• Show the average complexity: gocognit -avg .
• Ignore files matching a regex: gocognit -ignore "_test|testdata" .

You can install the gocognit command-line tool using either go install or go get.

go install github.com/uudashr/gocognit/cmd/gocognit@latest

or

go get github.com/uudashr/gocognit/cmd/gocognit

You can instruct gocognit to skip specific functions by adding the //gocognit:ignore directive immediately above the function definition.

//gocognit:ignore
func IgnoreMe() {
    // ...
}

You can instruct gocognit to skip specific functions by adding the following comment directly above the function declaration:

//gocognit:ignore
func MyComplexFunction() {
    // ...
}

The gocognit command-line tool calculates the cognitive complexity of Go functions and methods within specified files or directories. It can output results in a custom text format or as JSON, and supports filtering by complexity thresholds or top results.

Basic Usage:

gocognit [<flag> ...] <Go file or directory> ...

gocognit <Go file or directory>

To understand exactly how a specific complexity score was calculated, use the -d flag. When combined with -json, it provides a detailed breakdown of every increment and nesting level encountered during analysis.

gocognit -json -d .

The following flags are available for the gocognit command:

gocognit [<flag> ...] <Go file or directory> ...

To use gocognit in automated pipelines or for programmatic processing, use the -json flag. This will output an array of Stat objects.

Example:

gocognit -json ./pkg/mycode

To analyze all functions within a Go file, use ComplexityStats or ComplexityStatsWithDiagnostic. These functions iterate through the file's declarations, respect the //gocognit:ignore directive, and return a slice of Stat objects.

• ComplexityStats(f, fset, stats): Returns statistics without detailed diagnostics.
• ComplexityStatsWithDiagnostic(f, fset, stats, enableDiagnostics): Returns statistics including detailed Diagnostic information for each function.

// stats is an existing slice of gocognit.Stat to append to
fileStats := gocognit.ComplexityStats(astFile, fileSet, stats)