iface

iface is a linter designed to identify the incorrect use of interfaces in Go code, helping developers avoid interface pollution. By detecting unnecessary or poorly implemented interfaces, iface ensures your Go code remains clean, efficient, and maintainable.

It consists of several analyzers:

1. unused: Detects interfaces which are not used anywhere in the same package where they are defined.
2. unusedmethod: Detects interface methods that are never used anywhere in the same package where they are defined.
3. identical: Detects interfaces within the same package that have identical methods or type constraints.
4. opaque: Detects functions that return an interface type, but only ever return a single concrete implementation.
5. unexported: Detects interfaces which are not exported but are used as parameters or return values in exported functions or methods.

Usage

To install the linter which has all the checks:

go install github.com/uudashr/iface/cmd/ifacecheck@latest

To install individual linter, use the following command:

go install github.com/uudashr/iface/unused/cmd/unusediface@latest
go install github.com/uudashr/iface/unusedmethod/cmd/unusedmethodiface@latest
go install github.com/uudashr/iface/identical/cmd/identicaliface@latest
go install github.com/uudashr/iface/opaque/cmd/opaqueiface@latest
go install github.com/uudashr/iface/unexported/cmd/unexportediface@latest

Run the linter

ifacecheck ./...

or show the help

ifacecheck help

# or
ifacecheck help <analyzer-name>

Golangci-lint

The analyzers are also available in golangci-lint. It is sufficient to use them via golangci-lint. You can enable them by adding iface in the settings.

By default it only enables the identical analyzer, you need to enable them all to get the best of interface pollution detection.

Exclusion

Package exclusion

We encourage using the default behavior and making an effort to follow the rules. However, in some cases the rules may not apply. Due to this we can exclude specific package to be scanned by the analyzers. Use -unused.exclude or -unusedmethod.exclude flag. See help for more information:

Example usage:

ifacecheck -unused.exclude=github.com/example/log ./...
ifacecheck -unusedmethod.exclude=github.com/example/log ./...

Ignore Directive

Exclusion can be done by placing the //iface:ignore directive in the code to prevent it from being scanned by the analyzer. Example:

1. iface:ignore to ignore from all analyzers.
2. iface:ignore=[analyzer names] a comma-separated list of analyzer names to exclude from specific analyzers. Ex:
   • iface:ignore=unused ignore from unused analyzer.
   • iface:ignore=unused,identical ignore from unused and identical analyzers.

Note: use exclusion with careful consideration.

Background

One of Go's powerful features is interfaces. However, sometimes people misuse the interfaces even though the code works but the code becomes polluted with interfaces.

The following quotes inspired the creation of these analyzers:

"Go interfaces generally belong in the package that uses values of the interface type, not the package that implements those values. The implementing package should return concrete (usually pointer or struct) types: that way, new methods can be added to implementations without requiring extensive refactoring."

Go Code Review Comments, go.dev

"Don’t export any interfaces until you have to."

Interface pollution in Go, rakyll.org

"The use of interfaces when they are not necessary is called interface pollution."

Avoid Interface Pollution, ardanlabs.com

"Go interfaces generally belong in the package that consumes values of the interface type, not a package that implements the interface type."

Go Style Decisions, google.github.io