gocyclo

README

gocyclo

Gocyclo calculates cyclomatic complexities of functions in Go source code.

Cyclomatic complexity is a code quality metric which can be used to identify code that needs refactoring. It measures the number of linearly independent paths through a function's source code.

The cyclomatic complexity of a function is calculated according to the following rules:

 1 is the base complexity of a function
+1 for each 'if', 'for', 'case', '&&' or '||'

A function with a higher cyclomatic complexity requires more test cases to cover all possible paths and is potentially harder to understand. The complexity can be reduced by applying common refactoring techniques that lead to smaller functions.

Installation

To install the gocyclo command, run

$ go install github.com/fzipp/gocyclo/cmd/gocyclo@latest

and put the resulting binary in one of your PATH directories if $GOPATH/bin isn't already in your PATH.

Usage

Calculate cyclomatic complexities of Go functions.
Usage:
    gocyclo [flags] <Go file or directory> ...

Flags:
    -over N               show functions with complexity > N only and
                          return exit code 1 if the set is non-empty
    -top N                show the top N most complex functions only
    -avg, -avg-short      show the average complexity over all functions;
                          the short option prints the value without a label
    -total, -total-short  show the total complexity for all functions;
                          the short option prints the value without a label
    -ignore REGEX         exclude files matching the given regular expression

The output fields for each line are:
<complexity> <package> <function> <file:line:column>

Examples

$ gocyclo .
$ gocyclo main.go
$ gocyclo -top 10 src/
$ gocyclo -over 25 docker
$ gocyclo -avg .
$ gocyclo -top 20 -ignore "_test|Godeps|vendor/" .
$ gocyclo -over 3 -avg gocyclo/

Example output:

9 gocyclo (*complexityVisitor).Visit complexity.go:30:1
8 main main cmd/gocyclo/main.go:53:1
7 gocyclo (*fileAnalyzer).analyzeDecl analyze.go:96:1
4 gocyclo Analyze analyze.go:24:1
4 gocyclo parseDirectives directives.go:27:1
4 gocyclo (Stats).SortAndFilter stats.go:52:1
Average: 2.72

Note that the average is calculated over all analyzed functions, not just the printed ones.

Ignoring individual functions

Individual functions can be ignored with a gocyclo:ignore directive:

//gocyclo:ignore
func f1() {
	// ...
}
    
//gocyclo:ignore
var f2 = func() {
	// ...
}

License

This project is free and open source software licensed under the BSD 3-Clause License.

Documentation

Overview

Package gocyclo calculates the cyclomatic complexities of functions and methods in Go source code.

Index

• func Complexity(fn ast.Node) int
• type Stat
  • func (s Stat) String() string
• type Stats
  • func Analyze(paths []string, ignore *regexp.Regexp) Stats
  • func AnalyzeASTFile(f *ast.File, fs *token.FileSet, s Stats) Stats
  • func (s Stats) AverageComplexity() float64
  • func (s Stats) SortAndFilter(top, over int) Stats
  • func (s Stats) TotalComplexity() uint64

Functions

func Complexity

func Complexity(fn ast.Node) int

Complexity calculates the cyclomatic complexity of a function. The 'fn' node is either a *ast.FuncDecl or a *ast.FuncLit.

Types

type Stat

type Stat struct {
	PkgName    string
	FuncName   string
	Complexity int
	Pos        token.Position
}

Stat holds the cyclomatic complexity of a function, along with its package and and function name and its position in the source code.

func (Stat) String

func (s Stat) String() string

String formats the cyclomatic complexity information of a function in the following format: "<complexity> <package> <function> <file:line:column>"

type Stats

type Stats []Stat

Stats hold the cyclomatic complexities of many functions.

func Analyze

func Analyze(paths []string, ignore *regexp.Regexp) Stats

Analyze calculates the cyclomatic complexities of the functions and methods in the Go source code files in the given paths. If a path is a directory all Go files under that directory are analyzed recursively. Files with paths matching the 'ignore' regular expressions are skipped. The 'ignore' parameter can be nil, meaning that no files are skipped.

func AnalyzeASTFile

func AnalyzeASTFile(f *ast.File, fs *token.FileSet, s Stats) Stats

AnalyzeASTFile calculates the cyclomatic complexities of the functions and methods in the abstract syntax tree (AST) of a parsed Go file and appends the results to the given Stats slice.

func (Stats) AverageComplexity

func (s Stats) AverageComplexity() float64

AverageComplexity calculates the average cyclomatic complexity of the cyclomatic complexities in s.

func (Stats) SortAndFilter

func (s Stats) SortAndFilter(top, over int) Stats

SortAndFilter sorts the cyclomatic complexities in s in descending order and returns a slice of s limited to the 'top' N entries with a cyclomatic complexity greater than 'over'. If 'top' is negative, i.e. -1, it does not limit the result. If 'over' is <= 0 it does not limit the result either, because a function has a base cyclomatic complexity of at least 1.

func (Stats) TotalComplexity

func (s Stats) TotalComplexity() uint64

TotalComplexity calculates the total sum of all cyclomatic complexities in s.