src/tools/clippy/book/src/lints.md

   1 # Clippy's Lints
   2
   3 Clippy offers a bunch of additional lints, to help its users write more correct
   4 and idiomatic Rust code. A full list of all lints, that can be filtered by
   5 category, lint level or keywords, can be found in the [Clippy lint
   6 documentation].
   7
   8 This chapter will give an overview of the different lint categories, which kind
   9 of lints they offer and recommended actions when you should see a lint out of
  10 that category. For examples, see the [Clippy lint documentation] and filter by
  11 category.
  12
  13 The different lint groups were defined in the [Clippy 1.0 RFC].
  14
  15 ## Correctness
  16
  17 The `clippy::correctness` group is the only lint group in Clippy which lints are
  18 deny-by-default and abort the compilation when triggered. This is for good
  19 reason: If you see a `correctness` lint, it means that your code is outright
  20 wrong or useless and you should try to fix it.
  21
  22 Lints in this category are carefully picked and should be free of false
  23 positives. So just `#[allow]`ing those lints is not recommended.
  24
  25 ## Suspicious
  26
  27 The `clippy::suspicious` group is similar to the correctness lints in that it
  28 contains lints that trigger on code that is really _sus_ and should be fixed. As
  29 opposed to correctness lints, it might be possible that the linted code is
  30 intentionally written like it is.
  31
  32 It is still recommended to fix code that is linted by lints out of this group
  33 instead of `#[allow]`ing the lint. In case you intentionally have written code
  34 that offends the lint you should specifically and locally `#[allow]` the lint
  35 and add give a reason why the code is correct as written.
  36
  37 ## Complexity
  38
  39 The `clippy::complexity` group offers lints that give you suggestions on how to
  40 simplify your code. It mostly focuses on code that can be written in a shorter
  41 and more readable way, while preserving the semantics.
  42
  43 If you should see a complexity lint, it usually means that you can remove or
  44 replace some code and it is recommended to do so. However, if you need the more
  45 complex code for some expressiveness reason, it is recommended to allow
  46 complexity lints on a case-by-case basis.
  47
  48 ## Perf
  49
  50 The `clippy::perf` group gives you suggestions on how you can increase the
  51 performance of your code. Those lints are mostly about code that the compiler
  52 can't trivially optimize, but has to be written in a slightly different way to
  53 make the optimizer's job easier.
  54
  55 Perf lints are usually easy to apply and it is recommended to do so.
  56
  57 ## Style
  58
  59 The `clippy::style` group is mostly about writing idiomatic code. Because style
  60 is subjective, this lint group is the most opinionated warn-by-default group in
  61 Clippy.
  62
  63 If you see a style lint, applying the suggestion usually makes your code more
  64 readable and idiomatic. But because we know that this is opinionated, feel free
  65 to sprinkle `#[allow]`s for style lints in your code or `#![allow]` a style lint
  66 on your whole crate if you disagree with the suggested style completely.
  67
  68 ## Pedantic
  69
  70 The `clippy::pedantic` group makes Clippy even more _pedantic_. You can enable
  71 the whole group with `#![warn(clippy::pedantic)]` in the `lib.rs`/`main.rs` of
  72 your crate. This lint group is for Clippy power users that want an in depth
  73 check of their code.
  74
  75 > _Note:_ Instead of enabling the whole group (like Clippy itself does), you may
  76 > want to cherry-pick lints out of the pedantic group.
  77
  78 If you enable this group, expect to also use `#[allow]` attributes generously
  79 throughout your code. Lints in this group are designed to be pedantic and false
  80 positives sometimes are intentional in order to prevent false negatives.
  81
  82 ## Restriction
  83
  84 The `clippy::restriction` group contains lints that will _restrict_ you from
  85 using certain parts of the Rust language. It is **not** recommended to enable
  86 the whole group, but rather cherry-pick lints that are useful for your code base
  87 and your use case.
  88
  89 > _Note:_ Clippy will produce a warning if it finds a
  90 > `#![warn(clippy::restriction)]` attribute in your code!
  91
  92 Lints from this group will restrict you in some way. If you enable a restriction
  93 lint for your crate it is recommended to also fix code that this lint triggers
  94 on. However, those lints are really strict by design and you might want to
  95 `#[allow]` them in some special cases, with a comment justifying that.
  96
  97 ## Cargo
  98
  99 The `clippy::cargo` group gives you suggestions on how to improve your
 100 `Cargo.toml` file. This might be especially interesting if you want to publish
 101 your crate and are not sure if you have all useful information in your
 102 `Cargo.toml`.
 103
 104 [Clippy lint documentation]: https://rust-lang.github.io/rust-clippy/
 105 [Clippy 1.0 RFC]: https://github.com/rust-lang/rfcs/blob/master/text/2476-clippy-uno.md#lint-audit-and-categories