Skip to content

Commit

Permalink
add a book page for lint subgroups
Browse files Browse the repository at this point in the history
  • Loading branch information
y21 committed Oct 25, 2024
1 parent 5873cb9 commit 5aeb08e
Show file tree
Hide file tree
Showing 20 changed files with 479 additions and 56 deletions.
1 change: 1 addition & 0 deletions book/src/SUMMARY.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,6 +7,7 @@
- [Configuration](configuration.md)
- [Lint Configuration](lint_configuration.md)
- [Clippy's Lints](lints.md)
- [Lint subgroups](lint_subgroups.md)
- [Continuous Integration](continuous_integration/README.md)
- [GitHub Actions](continuous_integration/github_actions.md)
- [GitLab CI](continuous_integration/gitlab.md)
Expand Down
218 changes: 218 additions & 0 deletions book/src/lint_subgroups.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,218 @@
# Lint subgroups

Clippy groups its lints into [9 primary categories](lints.md),
two of which are allow-by-default (pedantic and restriction).

One downside of having such few but broad categories for allow-by-default lints
is that it significantly decreases discoverability, as `restriction` often acts as a blanket category
for any lint that most users likely would not want enforced on their codebase.

This page should help with that, by defining more granular, unofficial lint (sub)groups.
For example, some people might not be interested in all the style-related `pedantic` lints,
but *are* interested in the `perf`-related ones, so these lints
can additionally be added to the [`perf_pedantic`](#perf_pedantic) subgroup.

<!--
NOTE: Do not edit the contents in between lint-subgroup-start and lint-subgroup-end manually.
Instead, change the `declare_clippy_lint!` macro invocation for the particular lint
to include it in (or remove it from) a subgroup and re-run `cargo dev update_lints`.
The descriptions however are fine to edit.
-->

## `perf_pedantic`

These are `pedantic` lints that look for code patterns that could be expressed in a more efficient way.
These would be candidates for the `perf` category, however suggestions made by them can also sometimes hurt readability
and obfuscate the meaning, so occasional `#[allow]`s are expected to be used.

<!-- lint-subgroup-start: perf_pedantic -->
Lints: `assigning_clones`, `inefficient_to_string`, `naive_bytecount`, `needless_bitwise_bool`, `trivially_copy_pass_by_ref`, `unnecessary_box_returns`, `unnecessary_join`

<details>
<summary>#![warn] attribute</summary>

```
#![warn(
clippy::assigning_clones,
clippy::inefficient_to_string,
clippy::naive_bytecount,
clippy::needless_bitwise_bool,
clippy::trivially_copy_pass_by_ref,
clippy::unnecessary_box_returns,
clippy::unnecessary_join
)]
```
</details>

<details>
<summary>Lint table</summary>

```
[lints.clippy]
assigning_clones = "warn"
inefficient_to_string = "warn"
naive_bytecount = "warn"
needless_bitwise_bool = "warn"
trivially_copy_pass_by_ref = "warn"
unnecessary_box_returns = "warn"
unnecessary_join = "warn"
```
</details>
<!-- lint-subgroup-end -->


## `perf_restriction`

These are `restriction` lints that can improve the performance of code, but are very specific
and sometimes *significantly* hurt readability with very little gain in the usual case.
These should ideally only be applied to specific functions or modules that were profiled
and where it is very clear that any performance gain matters.

As always (but especially here), you should double-check that applying these actually helps
and that any performance wins are worth the introduced complexity.

<!-- lint-subgroup-start: perf_restriction -->
Lints: `format_push_string`, `missing_asserts_for_indexing`

<details>
<summary>#![warn] attribute</summary>

```
#![warn(
clippy::format_push_string,
clippy::missing_asserts_for_indexing
)]
```
</details>

<details>
<summary>Lint table</summary>

```
[lints.clippy]
format_push_string = "warn"
missing_asserts_for_indexing = "warn"
```
</details>
<!-- lint-subgroup-end -->

## `perf_nursery`

These are `nursery` lints that either were previously in the `perf` category or are intended to be in `perf`
but have too many false positives.
Some of them may also be simply wrong in certain situations and end up slower,
so you should make sure to read the description to learn about possible edge cases.

<!-- lint-subgroup-start: perf_nursery -->
Lints: `iter_with_drain`, `mutex_integer`, `needless_collect`, `or_fun_call`, `redundant_clone`, `significant_drop_tightening`, `trivial_regex`

<details>
<summary>#![warn] attribute</summary>

```
#![warn(
clippy::iter_with_drain,
clippy::mutex_integer,
clippy::needless_collect,
clippy::or_fun_call,
clippy::redundant_clone,
clippy::significant_drop_tightening,
clippy::trivial_regex
)]
```
</details>

<details>
<summary>Lint table</summary>

```
[lints.clippy]
iter_with_drain = "warn"
mutex_integer = "warn"
needless_collect = "warn"
or_fun_call = "warn"
redundant_clone = "warn"
significant_drop_tightening = "warn"
trivial_regex = "warn"
```
</details>
<!-- lint-subgroup-end -->

## `panic`

These are `restriction` lints that look for patterns that can introduce panics.

Usually panics are not something that one should want to avoid and most of the time panicking is perfectly valid
(hence why these lints are in the `restriction` category),
but users may want to forbid any use of panicky functions altogether in specific contexts.

One use case could be to annotate `GlobalAlloc` impls in which unwinding is Undefined Behavior.

<!-- lint-subgroup-start: panic -->
Lints: `arithmetic_side_effects`, `expect_used`, `indexing_slicing`, `panic`, `string_slice`, `todo`, `unimplemented`, `unreachable`, `unwrap_used`

<details>
<summary>#![warn] attribute</summary>

```
#![warn(
clippy::arithmetic_side_effects,
clippy::expect_used,
clippy::indexing_slicing,
clippy::panic,
clippy::string_slice,
clippy::todo,
clippy::unimplemented,
clippy::unreachable,
clippy::unwrap_used
)]
```
</details>

<details>
<summary>Lint table</summary>

```
[lints.clippy]
arithmetic_side_effects = "warn"
expect_used = "warn"
indexing_slicing = "warn"
panic = "warn"
string_slice = "warn"
todo = "warn"
unimplemented = "warn"
unreachable = "warn"
unwrap_used = "warn"
```
</details>
<!-- lint-subgroup-end -->

## `debug`

These are lints that can be useful to disable in CI, as they might indicate that code needs more work
or has remaining debugging artifacts.

<!-- lint-subgroup-start: debug -->
Lints: `dbg_macro`, `todo`

<details>
<summary>#![warn] attribute</summary>

```
#![warn(
clippy::dbg_macro,
clippy::todo
)]
```
</details>

<details>
<summary>Lint table</summary>

```
[lints.clippy]
dbg_macro = "warn"
todo = "warn"
```
</details>
<!-- lint-subgroup-end -->
2 changes: 1 addition & 1 deletion clippy_dev/src/lib.rs
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
#![feature(let_chains)]
#![feature(let_chains, debug_closure_helpers)]
#![feature(rustc_private)]
#![warn(
trivial_casts,
Expand Down
Loading

0 comments on commit 5aeb08e

Please sign in to comment.