Skip to content

Commit fcdb36a

Browse files
y21y21
committed
add a book page for lint subgroups
1 parent 5873cb9 commit fcdb36a

21 files changed

+506
-61
lines changed

‎book/src/SUMMARY.md

+1
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,7 @@
77
- [Configuration](configuration.md)
88
- [Lint Configuration](lint_configuration.md)
99
- [Clippy's Lints](lints.md)
10+
- [Lint subgroups](lint_subgroups.md)
1011
- [Continuous Integration](continuous_integration/README.md)
1112
- [GitHub Actions](continuous_integration/github_actions.md)
1213
- [GitLab CI](continuous_integration/gitlab.md)

‎book/src/lint_subgroups.md

+218
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,218 @@
1+
# Lint subgroups
2+
3+
Clippy groups its lints into [9 primary categories](lints.md),
4+
two of which are allow-by-default (pedantic and restriction).
5+
6+
One downside of having such few but broad categories for allow-by-default lints
7+
is that it significantly decreases discoverability, as `restriction` often acts as a blanket category
8+
for any lint that most users likely would not want enforced on their codebase.
9+
10+
This page should help with that, by defining more granular, unofficial lint (sub)groups.
11+
For example, some people might not be interested in all the style-related `pedantic` lints,
12+
but *are* interested in the `perf`-related ones, so these lints
13+
can additionally be added to the [`perf_pedantic`](#perf_pedantic) subgroup.
14+
15+
<!--
16+
NOTE: Do not edit the contents in between lint-subgroup-start and lint-subgroup-end manually.
17+
Instead, change the `declare_clippy_lint!` macro invocation for the particular lint
18+
to include it in (or remove it from) a subgroup and re-run `cargo dev update_lints`.
19+
The descriptions however are fine to edit.
20+
-->
21+
22+
## `perf_pedantic`
23+
24+
These are `pedantic` lints that look for code patterns that could be expressed in a more efficient way.
25+
These would be candidates for the `perf` category, however suggestions made by them can also sometimes hurt readability
26+
and obfuscate the meaning, so occasional `#[allow]`s are expected to be used.
27+
28+
<!-- lint-subgroup-start: perf_pedantic -->
29+
Lints: `assigning_clones`, `inefficient_to_string`, `naive_bytecount`, `needless_bitwise_bool`, `trivially_copy_pass_by_ref`, `unnecessary_box_returns`, `unnecessary_join`
30+
31+
<details>
32+
<summary>#![warn] attribute</summary>
33+
34+
```
35+
#![warn(
36+
clippy::assigning_clones,
37+
clippy::inefficient_to_string,
38+
clippy::naive_bytecount,
39+
clippy::needless_bitwise_bool,
40+
clippy::trivially_copy_pass_by_ref,
41+
clippy::unnecessary_box_returns,
42+
clippy::unnecessary_join
43+
)]
44+
```
45+
</details>
46+
47+
<details>
48+
<summary>Lint table</summary>
49+
50+
```
51+
[lints.clippy]
52+
assigning_clones = "warn"
53+
inefficient_to_string = "warn"
54+
naive_bytecount = "warn"
55+
needless_bitwise_bool = "warn"
56+
trivially_copy_pass_by_ref = "warn"
57+
unnecessary_box_returns = "warn"
58+
unnecessary_join = "warn"
59+
```
60+
</details>
61+
<!-- lint-subgroup-end -->
62+
63+
64+
## `perf_restriction`
65+
66+
These are `restriction` lints that can improve the performance of code, but are very specific
67+
and sometimes *significantly* hurt readability with very little gain in the usual case.
68+
These should ideally only be applied to specific functions or modules that were profiled
69+
and where it is very clear that any performance gain matters.
70+
71+
As always (but especially here), you should double-check that applying these actually helps
72+
and that any performance wins are worth the introduced complexity.
73+
74+
<!-- lint-subgroup-start: perf_restriction -->
75+
Lints: `format_push_string`, `missing_asserts_for_indexing`
76+
77+
<details>
78+
<summary>#![warn] attribute</summary>
79+
80+
```
81+
#![warn(
82+
clippy::format_push_string,
83+
clippy::missing_asserts_for_indexing
84+
)]
85+
```
86+
</details>
87+
88+
<details>
89+
<summary>Lint table</summary>
90+
91+
```
92+
[lints.clippy]
93+
format_push_string = "warn"
94+
missing_asserts_for_indexing = "warn"
95+
```
96+
</details>
97+
<!-- lint-subgroup-end -->
98+
99+
## `perf_nursery`
100+
101+
These are `nursery` lints that either were previously in the `perf` category or are intended to be in `perf`
102+
but have too many false positives.
103+
Some of them may also be simply wrong in certain situations and end up slower,
104+
so you should make sure to read the description to learn about possible edge cases.
105+
106+
<!-- lint-subgroup-start: perf_nursery -->
107+
Lints: `iter_with_drain`, `mutex_integer`, `needless_collect`, `or_fun_call`, `redundant_clone`, `significant_drop_tightening`, `trivial_regex`
108+
109+
<details>
110+
<summary>#![warn] attribute</summary>
111+
112+
```
113+
#![warn(
114+
clippy::iter_with_drain,
115+
clippy::mutex_integer,
116+
clippy::needless_collect,
117+
clippy::or_fun_call,
118+
clippy::redundant_clone,
119+
clippy::significant_drop_tightening,
120+
clippy::trivial_regex
121+
)]
122+
```
123+
</details>
124+
125+
<details>
126+
<summary>Lint table</summary>
127+
128+
```
129+
[lints.clippy]
130+
iter_with_drain = "warn"
131+
mutex_integer = "warn"
132+
needless_collect = "warn"
133+
or_fun_call = "warn"
134+
redundant_clone = "warn"
135+
significant_drop_tightening = "warn"
136+
trivial_regex = "warn"
137+
```
138+
</details>
139+
<!-- lint-subgroup-end -->
140+
141+
## `panic`
142+
143+
These are `restriction` lints that look for patterns that can introduce panics.
144+
145+
Usually panics are not something that one should want to avoid and most of the time panicking is perfectly valid
146+
(hence why these lints are in the `restriction` category),
147+
but users may want to forbid any use of panicky functions altogether in specific contexts.
148+
149+
One use case could be to annotate `GlobalAlloc` impls in which unwinding is Undefined Behavior.
150+
151+
<!-- lint-subgroup-start: panic -->
152+
Lints: `arithmetic_side_effects`, `expect_used`, `indexing_slicing`, `panic`, `string_slice`, `todo`, `unimplemented`, `unreachable`, `unwrap_used`
153+
154+
<details>
155+
<summary>#![warn] attribute</summary>
156+
157+
```
158+
#![warn(
159+
clippy::arithmetic_side_effects,
160+
clippy::expect_used,
161+
clippy::indexing_slicing,
162+
clippy::panic,
163+
clippy::string_slice,
164+
clippy::todo,
165+
clippy::unimplemented,
166+
clippy::unreachable,
167+
clippy::unwrap_used
168+
)]
169+
```
170+
</details>
171+
172+
<details>
173+
<summary>Lint table</summary>
174+
175+
```
176+
[lints.clippy]
177+
arithmetic_side_effects = "warn"
178+
expect_used = "warn"
179+
indexing_slicing = "warn"
180+
panic = "warn"
181+
string_slice = "warn"
182+
todo = "warn"
183+
unimplemented = "warn"
184+
unreachable = "warn"
185+
unwrap_used = "warn"
186+
```
187+
</details>
188+
<!-- lint-subgroup-end -->
189+
190+
## `debug`
191+
192+
These are lints that can be useful to disable in CI, as they might indicate that code needs more work
193+
or has remaining debugging artifacts.
194+
195+
<!-- lint-subgroup-start: debug -->
196+
Lints: `dbg_macro`, `todo`
197+
198+
<details>
199+
<summary>#![warn] attribute</summary>
200+
201+
```
202+
#![warn(
203+
clippy::dbg_macro,
204+
clippy::todo
205+
)]
206+
```
207+
</details>
208+
209+
<details>
210+
<summary>Lint table</summary>
211+
212+
```
213+
[lints.clippy]
214+
dbg_macro = "warn"
215+
todo = "warn"
216+
```
217+
</details>
218+
<!-- lint-subgroup-end -->

‎clippy_dev/src/lib.rs

+1-1
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
#![feature(let_chains)]
1+
#![feature(let_chains, debug_closure_helpers)]
22
#![feature(rustc_private)]
33
#![warn(
44
trivial_casts,

0 commit comments

Comments
 (0)