RULES_DESCRIPTIONS.md

Description of available rules

List of all available rules.

• Description of available rules
  • add-constant
  • argument-limit
  • atomic
  • banned-characters
  • bare-return
  • blank-imports
  • bool-literal-in-expr
  • call-to-gc
  • cognitive-complexity
  • comment-spacings
  • comments-density
  • confusing-naming
  • confusing-results
  • constant-logical-expr
  • context-as-argument
  • context-keys-type
  • cyclomatic
  • datarace
  • deep-exit
  • defer
  • dot-imports
  • duplicated-imports
  • early-return
  • empty-block
  • empty-lines
  • enforce-map-style
  • enforce-slice-style
  • error-naming
  • error-return
  • error-strings
  • errorf
  • exported
  • file-header
  • flag-parameter
  • function-length
  • function-result-limit
  • get-return
  • identical-branches
  • if-return
  • import-alias-naming
  • import-shadowing
  • imports-blocklist
  • increment-decrement
  • indent-error-flow
  • line-length-limit
  • max-control-nesting
  • max-public-structs
  • modifies-parameter
  • modifies-value-receiver
  • nested-structs
  • optimize-operands-order
  • package-comments
  • range-val-address
  • range-val-in-closure
  • range
  • receiver-naming
  • redefines-builtin-id
  • redundant-import-alias
  • string-format
  • string-of-int
  • struct-tag
  • superfluous-else
  • time-equal
  • time-naming
  • unchecked-type-assertion
  • unconditional-recursion
  • unexported-naming
  • unexported-return
  • unhandled-error
  • unnecessary-stmt
  • unreachable-code
  • unused-parameter
  • unused-receiver
  • use-any
  • useless-break
  • var-declaration
  • var-naming
  • waitgroup-by-value

add-constant

Description: Suggests using constant for magic numbers and string literals.

Configuration:

• maxLitCount : (string) maximum number of instances of a string literal that are tolerated before warn.
• allowStr: (string) comma-separated list of allowed string literals
• allowInts: (string) comma-separated list of allowed integers
• allowFloats: (string) comma-separated list of allowed floats
• ignoreFuncs: (string) comma-separated list of function names regexp patterns to exclude

Example:

[rule.add-constant]
  arguments = [{ maxLitCount = "3", allowStrs = "\"\"", allowInts = "0,1,2", allowFloats = "0.0,0.,1.0,1.,2.0,2.", ignoreFuncs = "os\\.*,fmt\\.Println,make" }]

argument-limit

Description: Warns when a function receives more parameters than the maximum set by the rule's configuration. Enforcing a maximum number of parameters helps to keep the code readable and maintainable.

Configuration: (int) the maximum number of parameters allowed per function.

Example:

[rule.argument-limit]
  arguments =[4]

atomic

Description: Check for commonly mistaken usages of the sync/atomic package

Configuration: N/A

banned-characters

Description: Checks given banned characters in identifiers(func, var, const). Comments are not checked.

Configuration: This rule requires a slice of strings, the characters to ban.

Example:

[rule.banned-characters]
  arguments =["Ω","Σ","σ"]

bare-return

Description: Warns on bare (a.k.a. naked) returns

Configuration: N/A

blank-imports

Description: Blank import should be only in a main or test package, or have a comment justifying it.

Configuration: N/A

bool-literal-in-expr

Description: Using Boolean literals (true, false) in logic expressions may make the code less readable. This rule suggests removing Boolean literals from logic expressions.

Configuration: N/A

call-to-gc

Description: Explicitly invoking the garbage collector is, except for specific uses in benchmarking, very dubious.

The garbage collector can be configured through environment variables as described here.

Configuration: N/A

cognitive-complexity

Description: Cognitive complexity is a measure of how hard code is to understand. While cyclomatic complexity is good to measure "testability" of the code, cognitive complexity aims to provide a more precise measure of the difficulty of understanding the code. Enforcing a maximum complexity per function helps to keep code readable and maintainable.

Configuration: (int) the maximum function complexity

Example:

[rule.cognitive-complexity]
  arguments =[7]

comment-spacings

Description: Spots comments of the form:

//This is a malformed comment: no space between // and the start of the sentence

Configuration: ([]string) list of exceptions. For example, to accept comments of the form

//mypragma: activate something
//+optional

You need to add both "mypragma:" and "+optional" in the configuration

Example:

[rule.comment-spacings]
  arguments =["mypragma:", "+optional"]

comments-density

Description: Spots files not respecting a minimum value for the comments lines density metric = comment lines / (lines of code + comment lines) * 100

Configuration: (int) the minimum expected comments lines density.

Example:

[rule.comments-density]
  arguments =[15]

confusing-naming

Description: Methods or fields of struct that have names different only by capitalization could be confusing.

Configuration: N/A

confusing-results

Description: Function or methods that return multiple, no named, values of the same type could induce error.

Configuration: N/A

constant-logical-expr

Description: The rule spots logical expressions that evaluate always to the same value.

Configuration: N/A

context-as-argument

Description: By convention, context.Context should be the first parameter of a function. This rule spots function declarations that do not follow the convention.

Configuration:

• allowTypesBefore : (string) comma-separated list of types that may be before 'context.Context'

Example:

[rule.context-as-argument]
  arguments = [{allowTypesBefore = "*testing.T,*github.com/user/repo/testing.Harness"}]

context-keys-type

Description: Basic types should not be used as a key in context.WithValue.

Configuration: N/A

cyclomatic

Description: Cyclomatic complexity is a measure of code complexity. Enforcing a maximum complexity per function helps to keep code readable and maintainable.

Configuration: (int) the maximum function complexity

Example:

[rule.cyclomatic]
  arguments =[3]

datarace

Description: This rule spots potential dataraces caused by go-routines capturing (by-reference) particular identifiers of the function from which go-routines are created. The rule is able to spot two of such cases: go-routines capturing named return values, and capturing for-range values.

Configuration: N/A

deep-exit

Description: Packages exposing functions that can stop program execution by exiting are hard to reuse. This rule looks for program exits in functions other than main() or init().

Configuration: N/A

defer

Description: This rule warns on some common mistakes when using defer statement. It currently alerts on the following situations:

name	description
call-chain	even if deferring call-chains of the form foo()() is valid, it does not helps code understanding (only the last call is deferred)
loop	deferring inside loops can be misleading (deferred functions are not executed at the end of the loop iteration but of the current function) and it could lead to exhausting the execution stack
method-call	deferring a call to a method can lead to subtle bugs if the method does not have a pointer receiver
recover	calling recover outside a deferred function has no effect
immediate-recover	calling recover at the time a defer is registered, rather than as part of the deferred callback. e.g. defer recover() or equivalent.
return	returning values form a deferred function has no effect

These gotchas are described here

Configuration: by default all warnings are enabled but it is possible selectively enable them through configuration. For example to enable only call-chain and loop:

[rule.defer]
  arguments=[["call-chain","loop"]]

dot-imports

Description: Importing with . makes the programs much harder to understand because it is unclear whether names belong to the current package or to an imported package.

More information here

Configuration:

• allowedPackages: (list of strings) comma-separated list of allowed dot import packages

Example:

[rule.dot-imports]
  arguments = [{ allowedPackages = ["github.com/onsi/ginkgo/v2","github.com/onsi/gomega"] }]

duplicated-imports

Description: It is possible to unintentionally import the same package twice. This rule looks for packages that are imported two or more times.

Configuration: N/A

early-return

Description: In Go it is idiomatic to minimize nesting statements, a typical example is to avoid if-then-else constructions. This rule spots constructions like

if cond {
  // do something
} else {
  // do other thing
  return ...
}

where the if condition may be inverted in order to reduce nesting:

if !cond {
  // do other thing
  return ...
}

// do something

Configuration: ([]string) rule flags. Available flags are:

• preserveScope: do not suggest refactorings that would increase variable scope

Example:

[rule.early-return]
  arguments = ["preserveScope"]

empty-block

Description: Empty blocks make code less readable and could be a symptom of a bug or unfinished refactoring.

Configuration: N/A

empty-lines

Description: Sometimes gofmt is not enough to enforce a common formatting of a code-base; this rule warns when there are heading or trailing newlines in code blocks.

Configuration: N/A

error-naming

Description: By convention, for the sake of readability, variables of type error must be named with the prefix err.

Configuration: N/A

error-return

Description: By convention, for the sake of readability, the errors should be last in the list of returned values by a function.

Configuration: N/A

error-strings

Description: By convention, for better readability, error messages should not be capitalized or end with punctuation or a newline.

More information here

Configuration: N/A

errorf

Description: It is possible to get a simpler program by replacing errors.New(fmt.Sprintf()) with fmt.Errorf(). This rule spots that kind of simplification opportunities.

Configuration: N/A

enforce-map-style

Description: This rule enforces consistent usage of make(map[type]type) or map[type]type{} for map initialization. It does not affect make(map[type]type, size) constructions as well as map[type]type{k1: v1}.

Configuration: (string) Specifies the enforced style for map initialization. The options are:

• "any": No enforcement (default).
• "make": Enforces the usage of make(map[type]type).
• "literal": Enforces the usage of map[type]type{}.

Example:

[rule.enforce-map-style]
  arguments = ["make"]

enforce-repeated-arg-type-style

Description: This rule is designed to maintain consistency in the declaration of repeated argument and return value types in Go functions. It supports three styles: 'any', 'short', and 'full'. The 'any' style is lenient and allows any form of type declaration. The 'short' style encourages omitting repeated types for conciseness, whereas the 'full' style mandates explicitly stating the type for each argument and return value, even if they are repeated, promoting clarity.

Configuration (1): (string) as a single string, it configures both argument and return value styles. Accepts 'any', 'short', or 'full' (default: 'any').

Configuration (2): (map[string]any) as a map, allows separate configuration for function arguments and return values. Valid keys are "funcArgStyle" and "funcRetValStyle", each accepting 'any', 'short', or 'full'. If a key is not specified, the default value of 'any' is used.

Note: The rule applies checks based on the specified styles. For 'full' style, it flags instances where types are omitted in repeated arguments or return values. For 'short' style, it highlights opportunities to omit repeated types for brevity. Incorrect or unknown configuration values will result in an error.

Example (1):

[rule.enforce-repeated-arg-type-style]
arguments = ["short"]

Example (2):

[rule.enforce-repeated-arg-type-style]
arguments = [ { funcArgStyle = "full", funcRetValStyle = "short" } ]

enforce-slice-style

Description: This rule enforces consistent usage of make([]type, 0), []type{}, or var []type for slice initialization. It does not affect make([]type, non_zero_len, or_non_zero_cap) constructions as well as []type{v1}. Nil slices are always permitted.

Configuration: (string) Specifies the enforced style for slice initialization. The options are:

• "any": No enforcement (default).
• "make": Enforces the usage of make([]type, 0).
• "literal": Enforces the usage of []type{}.
• "nil": Enforces the usage of var []type.

Example:

[rule.enforce-slice-style]
  arguments = ["make"]

exported

Description: Exported function and methods should have comments. This warns on undocumented exported functions and methods.

More information here

Configuration: ([]string) rule flags. Please notice that without configuration, the default behavior of the rule is that of its golint counterpart. Available flags are:

• checkPrivateReceivers enables checking public methods of private types
• disableStutteringCheck disables checking for method names that stutter with the package name (i.e. avoid failure messages of the form type name will be used as x.XY by other packages, and that stutters; consider calling this Y)
• sayRepetitiveInsteadOfStutters replaces the use of the term stutters by repetitive in failure messages

Example:

[rule.exported]
  arguments =["checkPrivateReceivers","disableStutteringCheck"]

file-header

Description: This rule helps to enforce a common header for all source files in a project by spotting those files that do not have the specified header.

Configuration: (string) the header to look for in source files.

Example:

[rule.file-header]
  arguments =["This is the text that must appear at the top of source files."]

flag-parameter

Description: If a function controls the flow of another by passing it information on what to do, both functions are said to be control-coupled. Coupling among functions must be minimized for better maintainability of the code. This rule warns on boolean parameters that create a control coupling.

Configuration: N/A

function-result-limit

Description: Functions returning too many results can be hard to understand/use.

Configuration: (int) the maximum allowed return values

Example:

[rule.function-result-limit]
  arguments =[3]

function-length

Description: Functions too long (with many statements and/or lines) can be hard to understand.

Configuration: (int,int) the maximum allowed statements and lines. Must be non-negative integers. Set to 0 to disable the check

Example:

[rule.function-length]
  arguments =[10,0]

Will check for functions exceeding 10 statements and will not check the number of lines of functions

get-return

Description: Typically, functions with names prefixed with Get are supposed to return a value.

Configuration: N/A

identical-branches

Description: an if-then-else conditional with identical implementations in both branches is an error.

Configuration: N/A

if-return

Description: Checking if an error is nil to just after return the error or nil is redundant.

Configuration: N/A

import-alias-naming

Description: Aligns with Go's naming conventions, as outlined in the official blog post. It enforces clear and lowercase import alias names, echoing the principles of good package naming. Users can follow these guidelines by default or define a custom regex rule. Importantly, aliases with underscores ("_") are always allowed.

Configuration (1): (string) as plain string accepts allow regexp pattern for aliases (default: ^[a-z][a-z0-9]{0,}$).

Configuration (2): (map[string]string) as a map accepts two values:

• for a key "allowRegex" accepts allow regexp pattern
• for a key "denyRegex deny regexp pattern

Note: If both allowRegex and denyRegex are provided, the alias must comply with both of them. If none are given (i.e. an empty map), the default value ^[a-z][a-z0-9]{0,}$ for allowRegex is used. Unknown keys will result in an error.

Example (1):

[rule.import-alias-naming]
  arguments = ["^[a-z][a-z0-9]{0,}$"]

Example (2):

[rule.import-alias-naming]
  arguments = [ { allowRegex = "^[a-z][a-z0-9]{0,}$", denyRegex = '^v\d+$' } ]

import-shadowing

Description: In GO it is possible to declare identifiers (packages, structs, interfaces, parameters, receivers, variables, constants...) that conflict with the name of an imported package. This rule spots identifiers that shadow an import.

Configuration: N/A

imports-blocklist

Description: Warns when importing block-listed packages.

Configuration: block-list of package names (or regular expression package names).

Example:

[imports-blocklist]
  arguments =["crypto/md5", "crypto/sha1", "crypto/**/pkix"]

increment-decrement

Description: By convention, for better readability, incrementing an integer variable by 1 is recommended to be done using the ++ operator. This rule spots expressions like i += 1 and i -= 1 and proposes to change them into i++ and i--.

Configuration: N/A

indent-error-flow

Description: To improve the readability of code, it is recommended to reduce the indentation as much as possible. This rule highlights redundant else-blocks that can be eliminated from the code.

More information here

Configuration: ([]string) rule flags. Available flags are:

• preserveScope: do not suggest refactorings that would increase variable scope

Example:

[rule.indent-error-flow]
  arguments = ["preserveScope"]

line-length-limit

Description: Warns in the presence of code lines longer than a configured maximum.

Configuration: (int) maximum line length in characters.

Example:

[rule.line-length-limit]
  arguments =[80]

max-control-nesting

Description: Warns if nesting level of control structures (if-then-else, for, switch) exceeds a given maximum.

Configuration: (int) maximum accepted nesting level of control structures (defaults to 5)

Example:

[max-control-nesting]
  arguments =[3]

max-public-structs

Description: Packages declaring too many public structs can be hard to understand/use, and could be a symptom of bad design.

This rule warns on files declaring more than a configured, maximum number of public structs.

Configuration: (int) the maximum allowed public structs

Example:

[rule.max-public-structs]
  arguments =[3]

modifies-parameter

Description: A function that modifies its parameters can be hard to understand. It can also be misleading if the arguments are passed by value by the caller. This rule warns when a function modifies one or more of its parameters.

Configuration: N/A

modifies-value-receiver

Description: A method that modifies its receiver value can have undesired behavior. The modification can be also the root of a bug because the actual value receiver could be a copy of that used at the calling site. This rule warns when a method modifies its receiver.

Configuration: N/A

nested-structs

Description: Packages declaring structs that contain other inline struct definitions can be hard to understand/read for other developers.

Configuration: N/A

optimize-operands-order

Description: conditional expressions can be written to take advantage of short circuit evaluation and speed up its average evaluation time by forcing the evaluation of less time-consuming terms before more costly ones. This rule spots logical expressions where the order of evaluation of terms seems non optimal. Please notice that confidence of this rule is low and is up to the user to decide if the suggested rewrite of the expression keeps the semantics of the original one.

Configuration: N/A

Example:

if isGenerated(content) && !config.IgnoreGeneratedHeader {

Swap left and right side :

if !config.IgnoreGeneratedHeader && isGenerated(content) {

package-comments

Description: Packages should have comments. This rule warns on undocumented packages and when packages comments are detached to the package keyword.

More information here

Configuration: N/A

range-val-address

Description: Range variables in a loop are reused at each iteration. This rule warns when assigning the address of the variable, passing the address to append() or using it in a map.

Configuration: N/A

range-val-in-closure

Description: Range variables in a loop are reused at each iteration; therefore a goroutine created in a loop will point to the range variable with from the upper scope. This way, the goroutine could use the variable with an undesired value. This rule warns when a range value (or index) is used inside a closure

Configuration: N/A

range

Description: This rule suggests a shorter way of writing ranges that do not use the second value.

Configuration: N/A

receiver-naming

Description: By convention, receiver names in a method should reflect their identity. For example, if the receiver is of type Parts, p is an adequate name for it. Contrary to other languages, it is not idiomatic to name receivers as this or self.

Configuration: N/A

redefines-builtin-id

Description: Constant names like false, true, nil, function names like append, make, and basic type names like bool, and byte are not reserved words of the language; therefore the can be redefined. Even if possible, redefining these built in names can lead to bugs very difficult to detect.

Configuration: N/A

redundant-import-alias

Description: This rule warns on redundant import aliases. This happens when the alias used on the import statement matches the imported package name.

Configuration: N/A

string-format

Description: This rule allows you to configure a list of regular expressions that string literals in certain function calls are checked against. This is geared towards user facing applications where string literals are often used for messages that will be presented to users, so it may be desirable to enforce consistent formatting.

Configuration: Each argument is a slice containing 2-3 strings: a scope, a regex, and an optional error message.

1. The first string defines a scope. This controls which string literals the regex will apply to, and is defined as a function argument. It must contain at least a function name (core.WriteError). Scopes may optionally contain a number specifying which argument in the function to check (core.WriteError[1]), as well as a struct field (core.WriteError[1].Message, only works for top level fields). Function arguments are counted starting at 0, so [0] would refer to the first argument, [1] would refer to the second, etc. If no argument number is provided, the first argument will be used (same as [0]).

2. The second string is a regular expression (beginning and ending with a / character), which will be used to check the string literals in the scope. The default semantics is "strings matching the regular expression are OK". If you need to inverse the semantics you can add a ! just before the first /. Examples:

   • with "/^[A-Z].*$/" the rule will accept strings starting with capital letters
   • with "!/^[A-Z].*$/" the rule will a fail on strings starting with capital letters

3. The third string (optional) is a message containing the purpose for the regex, which will be used in lint errors.

Example:

[rule.string-format]
  arguments = [
    ["core.WriteError[1].Message", "/^([^A-Z]|$)/", "must not start with a capital letter"],
    ["fmt.Errorf[0]", "/(^|[^\\.!?])$/", "must not end in punctuation"],
    ["panic", "/^[^\\n]*$/", "must not contain line breaks"]]

string-of-int

Description: explicit type conversion string(i) where i has an integer type other than rune might behave not as expected by the developer (e.g. string(42) is not "42"). This rule spot that kind of suspicious conversions.

Configuration: N/A

struct-tag

Description: Struct tags are not checked at compile time. This rule, checks and warns if it finds errors in common struct tags types like: asn1, default, json, protobuf, xml, yaml.

Configuration: (optional) list of user defined options.

Example: To accept the inline option in JSON tags (and outline and gnu in BSON tags) you must provide the following configuration

[rule.struct-tag]
  arguments = ["json,inline","bson,outline,gnu"]

superfluous-else

Description: To improve the readability of code, it is recommended to reduce the indentation as much as possible. This rule highlights redundant else-blocks that can be eliminated from the code.

Configuration: ([]string) rule flags. Available flags are:

• preserveScope: do not suggest refactorings that would increase variable scope

Example:

[rule.superfluous-else]
  arguments = ["preserveScope"]

time-equal

Description: This rule warns when using == and != for equality check time.Time and suggest to time.time.Equal method, for about information follow this link

Configuration: N/A

time-naming

Description: Using unit-specific suffix like "Secs", "Mins", ... when naming variables of type time.Duration can be misleading, this rule highlights those cases.

Configuration: N/A

unchecked-type-assertion

Description: This rule checks whether a type assertion result is checked (the ok value), preventing unexpected panics.

Configuration: list of key-value-pair-map ([]map[string]any).

• acceptIgnoredAssertionResult : (bool) default false, set it to true to accept ignored type assertion results like this:

foo, _ := bar(.*Baz).
//   ^

Example:

[rule.unchecked-type-assertion]
arguments = [{acceptIgnoredAssertionResult=true}]

unconditional-recursion

Description: Unconditional recursive calls will produce infinite recursion, thus program stack overflow. This rule detects and warns about unconditional (direct) recursive calls.

Configuration: N/A

unexported-naming

Description: this rule warns on wrongly named un-exported symbols, i.e. un-exported symbols whose name start with a capital letter.

Configuration: N/A

unexported-return

Description: This rule warns when an exported function or method returns a value of an un-exported type.

Configuration: N/A

unhandled-error

Description: This rule warns when errors returned by a function are not explicitly handled on the caller side.

Configuration: function names regexp patterns to ignore

Example:

[unhandled-error]
  arguments =["os\.(Create|WriteFile|Chmod)", "fmt\.Print", "myFunction", "net\..*", "bytes\.Buffer\.Write"]

unnecessary-stmt

Description: This rule suggests to remove redundant statements like a break at the end of a case block, for improving the code's readability.

Configuration: N/A

unreachable-code

Description: This rule spots and proposes to remove unreachable code.

Configuration: N/A

unused-parameter

Description: This rule warns on unused parameters. Functions or methods with unused parameters can be a symptom of an unfinished refactoring or a bug.

Configuration: Supports arguments with single of map[string]any with option allowRegex to provide additional to _ mask to allowed unused parameter names, for example:

[rule.unused-parameter]
    Arguments = [ { allowRegex = "^_" } ]

allows any names started with _, not just _ itself:

func SomeFunc(_someObj *MyStruct) {} // matches rule

unused-receiver

Description: This rule warns on unused method receivers. Methods with unused receivers can be a symptom of an unfinished refactoring or a bug.

Configuration: Supports arguments with single of map[string]any with option allowRegex to provide additional to _ mask to allowed unused receiver names, for example:

[rule.unused-receiver]
    Arguments = [ { allowRegex = "^_" } ]

allows any names started with _, not just _ itself:

func (_my *MyStruct) SomeMethod() {} // matches rule

use-any

Description: Since GO 1.18, interface{} has an alias: any. This rule proposes to replace instances of interface{} with any.

Configuration: N/A

useless-break

Description: This rule warns on useless break statements in case clauses of switch and select statements. GO, unlike other programming languages like C, only executes statements of the selected case while ignoring the subsequent case clauses. Therefore, inserting a break at the end of a case clause has no effect.

Because break statements are rarely used in case clauses, when switch or select statements are inside a for-loop, the programmer might wrongly assume that a break in a case clause will take the control out of the loop. The rule emits a specific warning for such cases.

Configuration: N/A

var-declaration

Description: This rule proposes simplifications of variable declarations.

Configuration: N/A

var-naming

Description: This rule warns when initialism, variable or package naming conventions are not followed.

Configuration: This rule accepts two slices of strings and one optional slice with single map with named parameters. (it's due to TOML hasn't "slice of any" and we keep backward compatibility with previous config version) First slice is an allowlist and second one is a blocklist of initialisms. In map, you can add "upperCaseConst=true" parameter to allow UPPER_CASE for const By default, the rule behaves exactly as the alternative in golint but optionally, you can relax it (see golint/lint/issues/89)

Example:

[rule.var-naming]
  arguments = [["ID"], ["VM"], [{upperCaseConst=true}]]

You can also add "skipPackageNameChecks=true" to skip package name checks.

Example:

[rule.var-naming]
  arguments = [[], [], [{skipPackageNameChecks=true}]]

waitgroup-by-value

Description: Function parameters that are passed by value, are in fact a copy of the original argument. Passing a copy of a sync.WaitGroup is usually not what the developer wants to do. This rule warns when a sync.WaitGroup expected as a by-value parameter in a function or method.

Configuration: N/A