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