go/revive
1
0
Fork 0
mirror of https://github.com/mgechev/revive.git synced 2025-02-15 13:53:15 +02:00
Code Issues Releases Activity

docs: update the documentation

Browse Source 
I did some formatting:

- There were new lines in the middle of few sentences
- Added newlines before code blocks
- Removed trailing spaces

I also dropped statements in the form "This rule checks/does/warns...", when this was clear from the rule's explanation.
This commit is contained in:
mgechev 2018-10-25 20:29:31 -07:00
parent 3ef16e4c45
commit 8e24648520
No known key found for this signature in database
GPG Key ID: A98CD29F2650FAD2
1 changed files with 43 additions and 55 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

98
RULES_DESCRIPTIONS.md
View File

@ -1,6 +1,6 @@
# Description of available rules # Description of available rules
List of all available rules. List of all available rules.
- [Description of available rules](#description-of-available-rules) - [Description of available rules](#description-of-available-rules)
@ -92,27 +92,25 @@ _Configuration_: N/A
## blank-imports ## blank-imports
_Description_: Blank import should be only in a main or test package, or have a comment justifying it; this rule warns if that is not the case. _Description_: Blank import should be only in a main or test package, or have a comment justifying it.
_Configuration_: N/A _Configuration_: N/A
## bool-literal-in-expr ## bool-literal-in-expr
_Description_: Using Boolean literals (`true`, `false`) in logic expressions may make the code less readable. This rule _Description_: Using Boolean literals (`true`, `false`) in logic expressions may make the code less readable. This rule suggests removing Boolean literals from logic expressions.
suggests removing Boolean literals from logic expressions.
_Configuration_: N/A _Configuration_: N/A
## confusing-naming ## confusing-naming
_Description_: Methods or fields of `struct`s that have similar names may be misleading. _Description_: Methods or fields of `struct` that have names different only by capitalization could be confusing.
Warns on methods and fields with names that differ only by capitalization.
_Configuration_: N/A _Configuration_: N/A
## confusing-results ## confusing-results
_Description_: Function or methods that return multiple, no named, values of the same type may induce error. This rule warns on those cases. _Description_: Function or methods that return multiple, no named, values of the same type could induce error.
_Configuration_: N/A _Configuration_: N/A
@ -124,25 +122,24 @@ _Configuration_: N/A
## context-as-argument ## context-as-argument
_Description_: Is a language [convention](https://github.com/golang/go/wiki/CodeReviewComments#contexts) that `context.Context` should be the first parameter of a function. This rule spots function declarations that do not follow the convention. _Description_: By [convention](https://github.com/golang/go/wiki/CodeReviewComments#contexts), `context.Context` should be the first parameter of a function. This rule spots function declarations that do not follow the convention.
_Configuration_: N/A _Configuration_: N/A
## context-keys-type ## context-keys-type
_Description_: Basic types should not be used as a key in `context.WithValue`. _Description_: Basic types should not be used as a key in `context.WithValue`.
This rule warns when that is the case.
_Configuration_: N/A _Configuration_: N/A
## cyclomatic ## cyclomatic
_Description_: [Cyclomatic complexity](https://en.wikipedia.org/wiki/Cyclomatic_complexity) is a measure of code complexity. _Description_: [Cyclomatic complexity](https://en.wikipedia.org/wiki/Cyclomatic_complexity) is a measure of code complexity. Enforcing a maximum complexity per function helps to keep code readable and maintainable.
Enforcing a maximum complexity per function helps to keep code readable and maintainable.
_Configuration_: (int) the maximum function complexity _Configuration_: (int) the maximum function complexity
Example: Example:
```toml ```toml
[cyclomatic] [cyclomatic]
arguments =[3] arguments =[3]
@ -155,41 +152,40 @@ _Description_: Packages exposing functions that can stop program execution by ex
_Configuration_: N/A _Configuration_: N/A
## dot-imports ## dot-imports
_Description_: Importing with `.` makes the programs much harder to understand because it is unclear where names belong to the current package or to an imported package.
This rule warns when using imports `.`
More information [here](https://github.com/golang/go/wiki/CodeReviewComments#import-dot) _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](https://github.com/golang/go/wiki/CodeReviewComments#import-dot)
_Configuration_: N/A _Configuration_: N/A
## empty-block ## empty-block
_Description_: Empty blocks make code less readable and may be a symptom of a bug or unfinished refactoring. This rule spots empty blocks in the code. _Description_: Empty blocks make code less readable and could be a symptom of a bug or unfinished refactoring.
_Configuration_: N/A _Configuration_: N/A
## empty-lines ## 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. _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 _Configuration_: N/A
## error-naming ## error-naming
_Description_: By convention, for the sake of readability, variables holding errors must be named with the prefix `err`. This rule warns when this convention is not followed. _Description_: By convention, for the sake of readability, variables of type `error` must be named with the prefix `err`.
_Configuration_: N/A _Configuration_: N/A
## error-return ## error-return
_Description_: By convention, for the sake of readability, the errors should be last in the list of returned values by a function. This rule warns when this convention is not followed. _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 _Configuration_: N/A
## error-strings ## error-strings
_Description_: By convention, for better readability, error messages should not be capitalized or end with punctuation or a newline. This rule warns when this convention is not followed. _Description_: By convention, for better readability, error messages should not be capitalized or end with punctuation or a newline.
More information [here](https://github.com/golang/go/wiki/CodeReviewComments#error-strings) More information [here](https://github.com/golang/go/wiki/CodeReviewComments#error-strings)
@ -203,8 +199,7 @@ _Configuration_: N/A
## exported ## exported
_Description_: Exported function and methods should have comments. _Description_: Exported function and methods should have comments. This warns on undocumented exported functions and methods.
This warns on undocumented exported functions and methods.
More information [here](https://github.com/golang/go/wiki/CodeReviewComments#doc-comments) More information [here](https://github.com/golang/go/wiki/CodeReviewComments#doc-comments)
@ -212,12 +207,12 @@ _Configuration_: N/A
## file-header ## file-header
_Description_: This rule helps to enforce a common header for all source files in a project _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.
by spotting those files that do not have the specified header.
_Configuration_: (string) the header to look for in source files. _Configuration_: (string) the header to look for in source files.
Example: Example:
```toml ```toml
[file-header] [file-header]
arguments =["This is the text that must appear at the top of source files."] arguments =["This is the text that must appear at the top of source files."]
@ -234,51 +229,52 @@ _Configuration_: N/A
## function-result-limit ## function-result-limit
_Description_: Functions returning too many results can be hard to understand/use. _Description_: Functions returning too many results can be hard to understand/use.
This rule warns on functions returning more than a configured, maximum number of values.
_Configuration_: (int) the maximum allowed return values _Configuration_: (int) the maximum allowed return values
Example: Example:
```toml ```toml
[function-result-limit] [function-result-limit]
arguments =[3] arguments =[3]
``` ```
## get-return ## get-return
_Description_: Typically, functions with names prefixed with _Get_ are supposed to return a value. _Description_: Typically, functions with names prefixed with _Get_ are supposed to return a value.
_Configuration_: N/A _Configuration_: N/A
## if-return ## if-return
_Description_: Checking if an error is _nil_ to just after return the error or nil is redundant; this rule warns on those cases. _Description_: Checking if an error is _nil_ to just after return the error or nil is redundant.
_Configuration_: N/A _Configuration_: N/A
## increment-decrement ## increment-decrement
_Description_: By convention, for better readability, incrementing an integer variable by 1 is recommended to be done using the `++` operator. _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--`. This rule spots expressions like `i += 1` and `i -= 1` and proposes to change them into `i++` and `i--`.
_Configuration_: N/A _Configuration_: N/A
## indent-error-flow ## indent-error-flow
_Description_: To improve the readability of code, it is recommended to reduce the indentation as much as possible. _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. This rule highlights redundant _else-blocks_ that can be eliminated from the code.
More information [here](https://github.com/golang/go/wiki/CodeReviewComments#indent-error-flow) More information [here](https://github.com/golang/go/wiki/CodeReviewComments#indent-error-flow)
_Configuration_: N/A _Configuration_: N/A
## imports-blacklist ## imports-blacklist
_Description_: This rule warns when importing black-listed packages. _Description_: Warns when importing black-listed packages.
_Configuration_: black-list of package names _Configuration_: black-list of package names
Example: Example:
```toml ```toml
[imports-blacklist] [imports-blacklist]
arguments =["crypto/md5", "crypto/sha1"] arguments =["crypto/md5", "crypto/sha1"]
@ -286,11 +282,12 @@ Example:
## line-lenght-limit ## line-lenght-limit
_Description_: This rule warns in the presence of code lines longer than a configured maximum. _Description_: Warns in the presence of code lines longer than a configured maximum.
_Configuration_: (int) maximum line length in characters. _Configuration_: (int) maximum line length in characters.
Example: Example:
```toml ```toml
[line-lenght-limit] [line-lenght-limit]
arguments =[80] arguments =[80]
@ -300,11 +297,13 @@ Example:
_Description_: Packages declaring too many public structs can be hard to understand/use, _Description_: Packages declaring too many public structs can be hard to understand/use,
and could be a symptom of bad design. and could be a symptom of bad design.
This rule warns on files declaring more than a configured, maximum number of public structs. This rule warns on files declaring more than a configured, maximum number of public structs.
_Configuration_: (int) the maximum allowed public structs _Configuration_: (int) the maximum allowed public structs
Example: Example:
```toml ```toml
[max-public-structs] [max-public-structs]
arguments =[3] arguments =[3]
@ -312,31 +311,27 @@ Example:
## modifies-parameter ## modifies-parameter
_Description_: A function that modifies its parameters can be hard to understand. _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.
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. This rule warns when a function modifies one or more of its parameters.
_Configuration_: N/A _Configuration_: N/A
## modifies-value-receiver ## modifies-value-receiver
_Description_: A method that modifies its receiver value can have undesired behavior. _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.
The modification can be also the root of a bug because the actual value receiver may be a copy of that used at the calling site.
This rule warns when a method modifies its receiver. This rule warns when a method modifies its receiver.
_Configuration_: N/A _Configuration_: N/A
## package-comments ## package-comments
_Description_: Packages should have comments. This rule warns on undocumented _Description_: Packages should have comments. This rule warns on undocumented packages and when packages comments are detached to the `package` keyword.
packages and when packages comments are detached to the `package` keyword.
More information [here](https://github.com/golang/go/wiki/CodeReviewComments#package-comments) More information [here](https://github.com/golang/go/wiki/CodeReviewComments#package-comments)
_Configuration_: N/A _Configuration_: N/A
## range ## range
_Description_: This rule suggests a shorter way of writing ranges that do not use the second value. _Description_: This rule suggests a shorter way of writing ranges that do not use the second value.
@ -344,41 +339,34 @@ _Configuration_: N/A
## range-val-in-closure ## 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 may use the variable with an undesired value. _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 This rule warns when a range value (or index) is used inside a closure
_Configuration_: N/A _Configuration_: N/A
## receiver-naming ## receiver-naming
_Description_: By convention, receiver names in a method should reflect their identity. _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`.
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`.
This rule warns when a receiver has a name, not in line with this convention.
_Configuration_: N/A _Configuration_: N/A
## redefines-builtin-id ## redefines-builtin-id
_Description_: Constant names like `false`, `true`, `nil`, function names like _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.
`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. Even if possible, redefining these built in names can lead to bugs very difficult to detect.
This rule, warns when a built-in identifier is redefined.
_Configuration_: N/A _Configuration_: N/A
## struct-tag ## struct-tag
_Description_: Struct tags are not checked at compile time. _Description_: Struct tags are not checked at compile time.
This rule, checks and warns if it founds errors in common struct tags types like: asn1, default, json, protobuf, xml, yaml. This rule, checks and warns if it finds errors in common struct tags types like: asn1, default, json, protobuf, xml, yaml.
_Configuration_: N/A _Configuration_: N/A
## superfluous-else ## superfluous-else
_Description_: To improve the readability of code, it is recommended to reduce the indentation as minimal as possible. _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. This rule highlights redundant _else-blocks_ that can be eliminated from the code.
_Configuration_: N/A _Configuration_: N/A
@ -396,6 +384,7 @@ _Description_: This rule warns when [variable](https://github.com/golang/go/wiki
_Configuration_: This rule accepts two slices of strings, a whitelist and a blacklist of initialisms. By default, the rule behaves exactly as the alternative in `golint` but optionally, you can relax it (see [golint/lint/issues/89](https://github.com/golang/lint/issues/89)) _Configuration_: This rule accepts two slices of strings, a whitelist and a blacklist of initialisms. By default, the rule behaves exactly as the alternative in `golint` but optionally, you can relax it (see [golint/lint/issues/89](https://github.com/golang/lint/issues/89))
Example: Example:
```toml ```toml
[rule.var-naming] [rule.var-naming]
arguments = [["ID"], ["VM"]] arguments = [["ID"], ["VM"]]
@ -415,7 +404,7 @@ _Configuration_: N/A
## unnecessary-stmt ## unnecessary-stmt
_Description_: To improve the readability of code, this rule suggests to remove redundant statements like a `break` at the end of a case block. _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 _Configuration_: N/A
@ -431,10 +420,9 @@ _Description_: This rule warns on unused parameters. Functions or methods with u
_Configuration_: N/A _Configuration_: N/A
## waitgroup-by-value ## waitgroup-by-value
_Description_: Function parameters that are passed by value, are in fact a copy of the original argument. _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.
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. This rule warns when a `sync.WaitGroup` expected as a by-value parameter in a function or method.
_Configuration_: N/A _Configuration_: N/A