Gocognit calculates cognitive complexities of functions (and methods) in Go source code. A measurement of how hard does the code is intuitively to understand.
Given code using if statement,
func GetWords(number int) string {
if number == 1 { // +1
return "one"
} else if number == 2 { // +1
return "a couple"
} else if number == 3 { // +1
return "a few"
} else { // +1
return "lots"
}
} // Cognitive complexity = 4Above code can be refactored using switch statement,
func GetWords(number int) string {
switch number { // +1
case 1:
return "one"
case 2:
return "a couple"
case 3:
return "a few"
default:
return "lots"
}
} // Cognitive complexity = 1As you see above codes are the same, but the second code are easier to understand, that is why the cognitive complexity score are lower compare to the first one.
func GetWords(number int) string { // +1
switch number {
case 1: // +1
return "one"
case 2: // +1
return "a couple"
case 3: // +1
return "a few"
default:
return "lots"
}
} // Cyclomatic complexity = 4func GetWords(number int) string {
switch number { // +1
case 1:
return "one"
case 2:
return "a couple"
case 3:
return "a few"
default:
return "lots"
}
} // Cognitive complexity = 1Cognitive complexity give lower score compare to cyclomatic complexity.
func SumOfPrimes(max int) int { // +1
var total int
OUT:
for i := 1; i < max; i++ { // +1
for j := 2; j < i; j++ { // +1
if i%j == 0 { // +1
continue OUT
}
}
total += i
}
return total
} // Cyclomatic complexity = 4func SumOfPrimes(max int) int {
var total int
OUT:
for i := 1; i < max; i++ { // +1
for j := 2; j < i; j++ { // +2 (nesting = 1)
if i%j == 0 { // +3 (nesting = 2)
continue OUT // +1
}
}
total += i
}
return total
} // Cognitive complexity = 7Cognitive complexity give higher score compare to cyclomatic complexity.
The cognitive complexity of a function is calculated according to the following rules:
Note: these rules are specific for Go, please see the original whitepaper for more complete reference.
There is an increment for each of the following:
if,else if,elseswitch,selectforgotoLABEL,breakLABEL,continueLABEL- sequence of binary logical operators
- each method in a recursion cycle
The following structures increment the nesting level:
if,else if,elseswitch,selectfor- function literal or lambda
The following structures receive a nesting increment commensurate with their nested depth inside nesting structures:
ifswitch,selectfor
go install github.com/uudashr/gocognit/cmd/gocognit@latestor
go get github.com/uudashr/gocognit/cmd/gocognit$ gocognit
Calculate cognitive complexities of Go functions.
Usage:
gocognit [<flag> ...] <Go file or directory> ...
Flags:
-over N show functions with complexity > N only
and return exit code 1 if the output is non-empty
-top N show the top N most complex functions only
-avg show the average complexity over all functions,
not depending on whether -over or -top are set
-test indicates whether test files should be included
-json encode the output as JSON
-d enable diagnostic output
-f format string the format to use
(default "{{.Complexity}} {{.PkgName}} {{.FuncName}} {{.Pos}}")
-ignore expr ignore files matching the given regexp
-exact-recursion work out what each call points to, the way the compiler
does, so recursion is scored exactly. Slower, and the code
must build; without it, mutually recursive methods may be
under-counted
The (default) output fields for each line are:
<complexity> <package> <function> <file:row:column>
The (default) output fields for each line are:
{{.Complexity}} {{.PkgName}} {{.FuncName}} {{.Pos}}
or equal to <complexity> <package> <function> <file:row:column>
The struct being passed to the template is:
type Stat struct {
PkgName string
FuncName string
Complexity int
Pos token.Position
Diagnostics []Diagnostics
}
type Diagnostic struct {
Inc string
Nesting int
Text string
Pos DiagnosticPosition
}
type DiagnosticPosition struct {
Offset int
Line int
Column int
}
Examples:
$ gocognit .
$ gocognit main.go
$ gocognit -top 10 src/
$ gocognit -over 25 docker
$ gocognit -avg .
$ gocognit -ignore "_test|testdata" .
The output fields for each line are:
<complexity> <package> <function> <file:row:column>
Recursion and
-exact-recursion. To score recursion, gocognit has to know which function each call actually goes to. By default it works that out from the source alone: fast, no build required, and fine for direct recursion and for cycles between top-level functions. It is not enough when methods call each other indirectly — for exampleWalkcallsn.Step()andStepcallsn.next.Walk()— because the type ofnis not visible in the syntax, so that cycle can be under-counted. When that might be happening, the CLI prints a one-time note on stderr. Pass-exact-recursionto have gocognit work out call targets the way the compiler does, giving exact recursion scores; it is slower and needs the code to build, and it falls back to the default mode with a warning if it cannot load.
Ignore individual functions by specifying gocognit:ignore directive.
//gocognit:ignore
func IgnoreMe() {
// ...
}To understand how the complexity are calculated, we can enable the diagnostic by using -d flag.
Example:
$ gocognit -json -d .It will show the diagnostic output in JSON format
JSON Output
[
{
"PkgName": "prime",
"FuncName": "SumOfPrimes",
"Complexity": 7,
"Pos": {
"Filename": "prime.go",
"Offset": 15,
"Line": 3,
"Column": 1
},
"Diagnostics": [
{
"Inc": 1,
"Text": "for",
"Pos": {
"Offset": 69,
"Line": 7,
"Column": 2
}
},
{
"Inc": 2,
"Nesting": 1,
"Text": "for",
"Pos": {
"Offset": 104,
"Line": 8,
"Column": 3
}
},
{
"Inc": 3,
"Nesting": 2,
"Text": "if",
"Pos": {
"Offset": 152,
"Line": 9,
"Column": 4
}
},
{
"Inc": 1,
"Text": "continue",
"Pos": {
"Offset": 190,
"Line": 10,
"Column": 5
}
}
]
}
]- Gocyclo where the code are based on.
- Cognitive Complexity: A new way of measuring understandability white paper by G. Ann Campbell.