github.com/Johnny2210/revive@v1.0.8-0.20210625134200-febf37ccd0f5/RULES_DESCRIPTIONS.md (about) 1 # Description of available rules 2 3 List of all available rules. 4 5 6 - [Description of available rules](#description-of-available-rules) 7 - [add-constant](#add-constant) 8 - [argument-limit](#argument-limit) 9 - [atomic](#atomic) 10 - [bare-return](#bare-return) 11 - [blank-imports](#blank-imports) 12 - [bool-literal-in-expr](#bool-literal-in-expr) 13 - [call-to-gc](#call-to-gc) 14 - [confusing-naming](#confusing-naming) 15 - [confusing-results](#confusing-results) 16 - [cognitive-complexity](#cognitive-complexity) 17 - [constant-logical-expr](#constant-logical-expr) 18 - [context-as-argument](#context-as-argument) 19 - [context-keys-type](#context-keys-type) 20 - [cyclomatic](#cyclomatic) 21 - [deep-exit](#deep-exit) 22 - [defer](#defer) 23 - [dot-imports](#dot-imports) 24 - [duplicated-imports](#duplicated-imports) 25 - [early-return](#early-return) 26 - [empty-block](#empty-block) 27 - [empty-lines](#empty-lines) 28 - [error-naming](#error-naming) 29 - [error-return](#error-return) 30 - [error-strings](#error-strings) 31 - [errorf](#errorf) 32 - [exported](#exported) 33 - [file-header](#file-header) 34 - [flag-parameter](#flag-parameter) 35 - [function-result-limit](#function-result-limit) 36 - [function-length](#function-length) 37 - [get-return](#get-return) 38 - [identical-branches](#identical-branches) 39 - [if-return](#if-return) 40 - [increment-decrement](#increment-decrement) 41 - [indent-error-flow](#indent-error-flow) 42 - [imports-blacklist](#imports-blacklist) 43 - [import-shadowing](#import-shadowing) 44 - [line-length-limit](#line-length-limit) 45 - [max-public-structs](#max-public-structs) 46 - [modifies-parameter](#modifies-parameter) 47 - [modifies-value-receiver](#modifies-value-receiver) 48 - [nested-structs](#nested-structs) 49 - [package-comments](#package-comments) 50 - [range](#range) 51 - [range-val-in-closure](#range-val-in-closure) 52 - [range-val-address](#range-val-address) 53 - [receiver-naming](#receiver-naming) 54 - [redefines-builtin-id](#redefines-builtin-id) 55 - [string-of-int](#string-of-int) 56 - [struct-tag](#struct-tag) 57 - [string-format](#string-format) 58 - [superfluous-else](#superfluous-else) 59 - [time-naming](#time-naming) 60 - [var-naming](#var-naming) 61 - [var-declaration](#var-declaration) 62 - [unconditional-recursion](#unconditional-recursion) 63 - [unexported-naming](#unexported-naming) 64 - [unexported-return](#unexported-return) 65 - [unhandled-error](#unhandled-error) 66 - [unnecessary-stmt](#unnecessary-stmt) 67 - [unreachable-code](#unreachable-code) 68 - [unused-parameter](#unused-parameter) 69 - [unused-receiver](#unused-receiver) 70 - [waitgroup-by-value](#waitgroup-by-value) 71 72 ## add-constant 73 74 _Description_: Suggests using constant for [magic numbers](https://en.wikipedia.org/wiki/Magic_number_(programming)#Unnamed_numerical_constants) and string literals. 75 76 _Configuration_: 77 78 * `maxLitCount` : (string) maximum number of instances of a string literal that are tolerated before warn. 79 * `allowStr`: (string) comma-separated list of allowed string literals 80 * `allowInts`: (string) comma-separated list of allowed integers 81 * `allowFloats`: (string) comma-separated list of allowed floats 82 83 Example: 84 85 ```toml 86 [rule.add-constant] 87 arguments = [{maxLitCount = "3",allowStrs ="\"\"",allowInts="0,1,2",allowFloats="0.0,0.,1.0,1.,2.0,2."}] 88 ``` 89 90 ## argument-limit 91 92 _Description_: Warns when a function receives more parameters than the maximum set by the rule's configuration. 93 Enforcing a maximum number of parameters helps to keep the code readable and maintainable. 94 95 _Configuration_: (int) the maximum number of parameters allowed per function. 96 97 Example: 98 99 ```toml 100 [rule.argument-limit] 101 arguments =[4] 102 ``` 103 104 ## atomic 105 106 _Description_: Check for commonly mistaken usages of the `sync/atomic` package 107 108 _Configuration_: N/A 109 110 ## bare-return 111 112 _Description_: Warns on bare (a.k.a. naked) returns 113 114 _Configuration_: N/A 115 116 ## blank-imports 117 118 _Description_: Blank import should be only in a main or test package, or have a comment justifying it. 119 120 _Configuration_: N/A 121 122 ## bool-literal-in-expr 123 124 _Description_: Using Boolean literals (`true`, `false`) in logic expressions may make the code less readable. This rule suggests removing Boolean literals from logic expressions. 125 126 _Configuration_: N/A 127 128 ## call-to-gc 129 130 _Description_: Explicitly invoking the garbage collector is, except for specific uses in benchmarking, very dubious. 131 132 The garbage collector can be configured through environment variables as described [here](https://golang.org/pkg/runtime/). 133 134 _Configuration_: N/A 135 136 ## cognitive-complexity 137 138 _Description_: [Cognitive complexity](https://www.sonarsource.com/resources/white-papers/cognitive-complexity.html) is a measure of how hard code is to understand. 139 While cyclomatic complexity is good to measure "testeability" of the code, cognitive complexity aims to provide a more precise measure of the difficulty of understanding the code. 140 Enforcing a maximum complexity per function helps to keep code readable and maintainable. 141 142 _Configuration_: (int) the maximum function complexity 143 144 Example: 145 146 ```toml 147 [rule.cognitive-complexity] 148 arguments =[7] 149 ``` 150 151 ## confusing-naming 152 153 _Description_: Methods or fields of `struct` that have names different only by capitalization could be confusing. 154 155 _Configuration_: N/A 156 157 ## confusing-results 158 159 _Description_: Function or methods that return multiple, no named, values of the same type could induce error. 160 161 _Configuration_: N/A 162 163 ## constant-logical-expr 164 165 _Description_: The rule spots logical expressions that evaluate always to the same value. 166 167 _Configuration_: N/A 168 169 ## context-as-argument 170 171 _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. 172 173 _Configuration_: N/A 174 175 ## context-keys-type 176 177 _Description_: Basic types should not be used as a key in `context.WithValue`. 178 179 _Configuration_: N/A 180 181 ## cyclomatic 182 183 _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. 184 185 _Configuration_: (int) the maximum function complexity 186 187 Example: 188 189 ```toml 190 [rule.cyclomatic] 191 arguments =[3] 192 ``` 193 194 ## deep-exit 195 196 _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()`. 197 198 _Configuration_: N/A 199 200 ## defer 201 202 _Description_: This rule warns on some common mistakes when using `defer` statement. It currently alerts on the following situations: 203 | name | description | 204 |------|-------------| 205 | 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)| 206 |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 | 207 | method-call| deferring a call to a method can lead to subtle bugs if the method does not have a pointer receiver| 208 | recover | calling `recover` outside a deferred function has no effect| 209 | return | returning values form a deferred function has no effect| 210 211 These gotchas are described [here](https://blog.learngoprogramming.com/gotchas-of-defer-in-go-1-8d070894cb01) 212 213 _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`: 214 215 ```toml 216 [rule.defer] 217 arguments=[["call-chain","loop"]] 218 ``` 219 220 ## dot-imports 221 222 _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. 223 224 More information [here](https://github.com/golang/go/wiki/CodeReviewComments#import-dot) 225 226 _Configuration_: N/A 227 228 ## duplicated-imports 229 230 _Description_: It is possible to unintentionally import the same package twice. This rule looks for packages that are imported two or more times. 231 232 _Configuration_: N/A 233 234 ### early-return 235 236 _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 237 ```go 238 if cond { 239 // do something 240 } else { 241 // do other thing 242 return ... 243 } 244 ``` 245 that can be rewritten into more idiomatic: 246 ```go 247 if ! cond { 248 // do other thing 249 return ... 250 } 251 252 // do something 253 ``` 254 255 _Configuration_: N/A 256 257 ## empty-block 258 259 _Description_: Empty blocks make code less readable and could be a symptom of a bug or unfinished refactoring. 260 261 _Configuration_: N/A 262 263 ## empty-lines 264 265 _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. 266 267 _Configuration_: N/A 268 269 ## error-naming 270 271 _Description_: By convention, for the sake of readability, variables of type `error` must be named with the prefix `err`. 272 273 _Configuration_: N/A 274 275 ## error-return 276 277 _Description_: By convention, for the sake of readability, the errors should be last in the list of returned values by a function. 278 279 _Configuration_: N/A 280 281 ## error-strings 282 283 _Description_: By convention, for better readability, error messages should not be capitalized or end with punctuation or a newline. 284 285 More information [here](https://github.com/golang/go/wiki/CodeReviewComments#error-strings) 286 287 _Configuration_: N/A 288 289 ## errorf 290 291 _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. 292 293 _Configuration_: N/A 294 295 ## exported 296 297 _Description_: Exported function and methods should have comments. This warns on undocumented exported functions and methods. 298 299 More information [here](https://github.com/golang/go/wiki/CodeReviewComments#doc-comments) 300 301 _Configuration_: N/A 302 303 ## file-header 304 305 _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. 306 307 _Configuration_: (string) the header to look for in source files. 308 309 Example: 310 311 ```toml 312 [rule.file-header] 313 arguments =["This is the text that must appear at the top of source files."] 314 ``` 315 316 ## flag-parameter 317 318 _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](https://en.wikipedia.org/wiki/Coupling_(computer_programming)#Procedural_programming). 319 Coupling among functions must be minimized for better maintainability of the code. 320 This rule warns on boolean parameters that create a control coupling. 321 322 _Configuration_: N/A 323 324 ## function-result-limit 325 326 _Description_: Functions returning too many results can be hard to understand/use. 327 328 _Configuration_: (int) the maximum allowed return values 329 330 Example: 331 332 ```toml 333 [rule.function-result-limit] 334 arguments =[3] 335 ``` 336 337 ## function-length 338 339 _Description_: Functions too long (with many statements and/or lines) can be hard to understand. 340 341 _Configuration_: (int,int) the maximum allowed statements and lines. Must be non-negative integers. Set to 0 to disable the check 342 343 Example: 344 345 ```toml 346 [rule.function-length] 347 arguments =[10,0] 348 ``` 349 Will check for functions exceeding 10 statements and will not check the number of lines of functions 350 351 ## get-return 352 353 _Description_: Typically, functions with names prefixed with _Get_ are supposed to return a value. 354 355 _Configuration_: N/A 356 357 ## identical-branches 358 359 _Description_: an `if-then-else` conditional with identical implementations in both branches is an error. 360 361 _Configuration_: N/A 362 363 ## if-return 364 365 _Description_: Checking if an error is _nil_ to just after return the error or nil is redundant. 366 367 _Configuration_: N/A 368 369 ## increment-decrement 370 371 _Description_: By convention, for better readability, incrementing an integer variable by 1 is recommended to be done using the `++` operator. 372 This rule spots expressions like `i += 1` and `i -= 1` and proposes to change them into `i++` and `i--`. 373 374 _Configuration_: N/A 375 376 ## indent-error-flow 377 378 _Description_: To improve the readability of code, it is recommended to reduce the indentation as much as possible. 379 This rule highlights redundant _else-blocks_ that can be eliminated from the code. 380 381 More information [here](https://github.com/golang/go/wiki/CodeReviewComments#indent-error-flow) 382 383 _Configuration_: N/A 384 385 ## imports-blacklist 386 387 _Description_: Warns when importing black-listed packages. 388 389 _Configuration_: black-list of package names 390 391 Example: 392 393 ```toml 394 [imports-blacklist] 395 arguments =["crypto/md5", "crypto/sha1"] 396 ``` 397 ### import-shadowing 398 399 _Description_: In GO it is possible to declare identifiers (packages, structs, 400 interfaces, parameters, receivers, variables, constants...) that conflict with the 401 name of an imported package. This rule spots identifiers that shadow an import. 402 403 _Configuration_: N/A 404 405 ## line-length-limit 406 407 _Description_: Warns in the presence of code lines longer than a configured maximum. 408 409 _Configuration_: (int) maximum line length in characters. 410 411 Example: 412 413 ```toml 414 [rule.line-length-limit] 415 arguments =[80] 416 ``` 417 418 ## max-public-structs 419 420 _Description_: Packages declaring too many public structs can be hard to understand/use, 421 and could be a symptom of bad design. 422 423 This rule warns on files declaring more than a configured, maximum number of public structs. 424 425 _Configuration_: (int) the maximum allowed public structs 426 427 Example: 428 429 ```toml 430 [rule.max-public-structs] 431 arguments =[3] 432 ``` 433 434 ## modifies-parameter 435 436 _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. 437 This rule warns when a function modifies one or more of its parameters. 438 439 _Configuration_: N/A 440 441 ## modifies-value-receiver 442 443 _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. 444 This rule warns when a method modifies its receiver. 445 446 _Configuration_: N/A 447 448 ## nested-structs 449 450 _Description_: Packages declaring structs that contain other inline struct definitions can be hard to understand/read for other developers. 451 452 _Configuration_: N/A 453 454 ## package-comments 455 456 _Description_: Packages should have comments. This rule warns on undocumented packages and when packages comments are detached to the `package` keyword. 457 458 More information [here](https://github.com/golang/go/wiki/CodeReviewComments#package-comments) 459 460 _Configuration_: N/A 461 462 ## range 463 464 _Description_: This rule suggests a shorter way of writing ranges that do not use the second value. 465 466 _Configuration_: N/A 467 468 ## range-val-in-closure 469 470 _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. 471 This rule warns when a range value (or index) is used inside a closure 472 473 _Configuration_: N/A 474 475 ## range-val-address 476 477 _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. 478 479 _Configuration_: N/A 480 481 ## receiver-naming 482 483 _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`. 484 485 _Configuration_: N/A 486 487 ## redefines-builtin-id 488 489 _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. 490 Even if possible, redefining these built in names can lead to bugs very difficult to detect. 491 492 _Configuration_: N/A 493 494 ## string-of-int 495 _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. 496 497 _Configuration_: N/A 498 499 ## string-format 500 501 _Description_: This rule allows you to configure a list of regular expressions that string literals in certain function calls are checked against. 502 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. 503 504 _Configuration_: Each argument is a slice containing 2-3 strings: a scope, a regex, and an optional error message. 505 506 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]`). 507 508 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. 509 510 3. The third string (optional) is a message containing the purpose for the regex, which will be used in lint errors. 511 512 Example: 513 514 ```toml 515 [rule.string-format] 516 arguments = [ 517 ["core.WriteError[1].Message", "/^([^A-Z]|$)/", "must not start with a capital letter"], 518 ["fmt.Errorf[0]", "/(^|[^\\.!?])$/", "must not end in punctuation"], 519 ["panic", "/^[^\\n]*$/", "must not contain line breaks"]] 520 ``` 521 522 ## struct-tag 523 524 _Description_: Struct tags are not checked at compile time. 525 This rule, checks and warns if it finds errors in common struct tags types like: asn1, default, json, protobuf, xml, yaml. 526 527 _Configuration_: N/A 528 529 ## superfluous-else 530 531 _Description_: To improve the readability of code, it is recommended to reduce the indentation as much as possible. 532 This rule highlights redundant _else-blocks_ that can be eliminated from the code. 533 534 _Configuration_: N/A 535 536 ## time-naming 537 538 _Description_: Using unit-specific suffix like "Secs", "Mins", ... when naming variables of type `time.Duration` can be misleading, this rule highlights those cases. 539 540 _Configuration_: N/A 541 542 ## var-naming 543 544 _Description_: This rule warns when [variable](https://github.com/golang/go/wiki/CodeReviewComments#variable-names) or [package](https://github.com/golang/go/wiki/CodeReviewComments#package-names) naming conventions are not followed. 545 546 _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)) 547 548 Example: 549 550 ```toml 551 [rule.var-naming] 552 arguments = [["ID"], ["VM"]] 553 ``` 554 555 ## var-declaration 556 557 _Description_: This rule proposes simplifications of variable declarations. 558 559 _Configuration_: N/A 560 561 ## unconditional-recursion 562 563 _Description_: Unconditional recursive calls will produce infinite recursion, thus program stack overflow. This rule detects and warns about unconditional (direct) recursive calls. 564 565 _Configuration_: N/A 566 567 ## unexported-naming 568 569 _Description_: this rule warns on wrongly named un-exported symbols, i.e. un-exported symbols whose name start with a capital letter. 570 571 _Configuration_: N/A 572 573 ## unexported-return 574 575 _Description_: This rule warns when an exported function or method returns a value of an un-exported type. 576 577 _Configuration_: N/A 578 579 ## unhandled-error 580 581 _Description_: This rule warns when errors returned by a function are not explicitly handled on the caller side. 582 583 _Configuration_: function names to ignore 584 585 Example: 586 587 ```toml 588 [unhandled-error] 589 arguments =["fmt.Printf", "myFunction"] 590 ``` 591 ## unnecessary-stmt 592 593 _Description_: This rule suggests to remove redundant statements like a `break` at the end of a case block, for improving the code's readability. 594 595 _Configuration_: N/A 596 597 ## unreachable-code 598 599 _Description_: This rule spots and proposes to remove [unreachable code](https://en.wikipedia.org/wiki/Unreachable_code). 600 601 _Configuration_: N/A 602 603 ## unused-parameter 604 605 _Description_: This rule warns on unused parameters. Functions or methods with unused parameters can be a symptom of an unfinished refactoring or a bug. 606 607 _Configuration_: N/A 608 609 ## unused-receiver 610 611 _Description_: This rule warns on unused method receivers. Methods with unused receivers can be a symptom of an unfinished refactoring or a bug. 612 613 _Configuration_: N/A 614 615 ## waitgroup-by-value 616 617 _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. 618 This rule warns when a `sync.WaitGroup` expected as a by-value parameter in a function or method. 619 620 _Configuration_: N/A