diff options
-rw-r--r-- | docs/dev/style.md | 46 |
1 files changed, 23 insertions, 23 deletions
diff --git a/docs/dev/style.md b/docs/dev/style.md index f4748160b..67cbc6744 100644 --- a/docs/dev/style.md +++ b/docs/dev/style.md | |||
@@ -53,7 +53,7 @@ We try to be very conservative with usage of crates.io dependencies. | |||
53 | Don't use small "helper" crates (exception: `itertools` is allowed). | 53 | Don't use small "helper" crates (exception: `itertools` is allowed). |
54 | If there's some general reusable bit of code you need, consider adding it to the `stdx` crate. | 54 | If there's some general reusable bit of code you need, consider adding it to the `stdx` crate. |
55 | 55 | ||
56 | **Rational:** keep compile times low, create ecosystem pressure for faster | 56 | **Rationale:** keep compile times low, create ecosystem pressure for faster |
57 | compiles, reduce the number of things which might break. | 57 | compiles, reduce the number of things which might break. |
58 | 58 | ||
59 | ## Commit Style | 59 | ## Commit Style |
@@ -78,7 +78,7 @@ Use original span for FileId | |||
78 | 78 | ||
79 | This makes it easier to prepare a changelog. | 79 | This makes it easier to prepare a changelog. |
80 | 80 | ||
81 | **Rational:** clean history is potentially useful, but rarely used. | 81 | **Rationale:** clean history is potentially useful, but rarely used. |
82 | But many users read changelogs. | 82 | But many users read changelogs. |
83 | 83 | ||
84 | ## Clippy | 84 | ## Clippy |
@@ -90,7 +90,7 @@ There's `cargo xtask lint` command which runs a subset of low-FPR lints. | |||
90 | Careful tweaking of `xtask lint` is welcome. | 90 | Careful tweaking of `xtask lint` is welcome. |
91 | Of course, applying Clippy suggestions is welcome as long as they indeed improve the code. | 91 | Of course, applying Clippy suggestions is welcome as long as they indeed improve the code. |
92 | 92 | ||
93 | **Rational:** see [rust-lang/clippy#5537](https://github.com/rust-lang/rust-clippy/issues/5537). | 93 | **Rationale:** see [rust-lang/clippy#5537](https://github.com/rust-lang/rust-clippy/issues/5537). |
94 | 94 | ||
95 | # Code | 95 | # Code |
96 | 96 | ||
@@ -126,7 +126,7 @@ fn main() { | |||
126 | } | 126 | } |
127 | ``` | 127 | ``` |
128 | 128 | ||
129 | **Rational:** | 129 | **Rationale:** |
130 | 130 | ||
131 | There are many benefits to this: | 131 | There are many benefits to this: |
132 | 132 | ||
@@ -157,7 +157,7 @@ fn frobnicate(walrus: Option<Walrus>) { | |||
157 | } | 157 | } |
158 | ``` | 158 | ``` |
159 | 159 | ||
160 | **Rational:** this makes control flow explicit at the call site. | 160 | **Rationale:** this makes control flow explicit at the call site. |
161 | Call-site has more context, it often happens that the precondition falls out naturally or can be bubbled up higher in the stack. | 161 | Call-site has more context, it often happens that the precondition falls out naturally or can be bubbled up higher in the stack. |
162 | 162 | ||
163 | Avoid splitting precondition check and precondition use across functions: | 163 | Avoid splitting precondition check and precondition use across functions: |
@@ -195,7 +195,7 @@ fn is_string_literal(s: &str) -> bool { | |||
195 | In the "Not as good" version, the precondition that `1` is a valid char boundary is checked in `is_string_literal` and used in `foo`. | 195 | In the "Not as good" version, the precondition that `1` is a valid char boundary is checked in `is_string_literal` and used in `foo`. |
196 | In the "Good" version, the precondition check and usage are checked in the same block, and then encoded in the types. | 196 | In the "Good" version, the precondition check and usage are checked in the same block, and then encoded in the types. |
197 | 197 | ||
198 | **Rational:** non-local code properties degrade under change. | 198 | **Rationale:** non-local code properties degrade under change. |
199 | 199 | ||
200 | When checking a boolean precondition, prefer `if !invariant` to `if negated_invariant`: | 200 | When checking a boolean precondition, prefer `if !invariant` to `if negated_invariant`: |
201 | 201 | ||
@@ -211,7 +211,7 @@ if idx >= len { | |||
211 | } | 211 | } |
212 | ``` | 212 | ``` |
213 | 213 | ||
214 | **Rational:** its useful to see the invariant relied upon by the rest of the function clearly spelled out. | 214 | **Rationale:** its useful to see the invariant relied upon by the rest of the function clearly spelled out. |
215 | 215 | ||
216 | ## Getters & Setters | 216 | ## Getters & Setters |
217 | 217 | ||
@@ -241,7 +241,7 @@ impl Person { | |||
241 | } | 241 | } |
242 | ``` | 242 | ``` |
243 | 243 | ||
244 | **Rational:** we don't provide public API, it's cheaper to refactor than to pay getters rent. | 244 | **Rationale:** we don't provide public API, it's cheaper to refactor than to pay getters rent. |
245 | Non-local code properties degrade under change, privacy makes invariant local. | 245 | Non-local code properties degrade under change, privacy makes invariant local. |
246 | Borrowed own data discloses irrelevant details about origin of data. | 246 | Borrowed own data discloses irrelevant details about origin of data. |
247 | Irrelevant (neither right nor wrong) things obscure correctness. | 247 | Irrelevant (neither right nor wrong) things obscure correctness. |
@@ -271,7 +271,7 @@ impl Foo { | |||
271 | 271 | ||
272 | Prefer `Default` even it has to be implemented manually. | 272 | Prefer `Default` even it has to be implemented manually. |
273 | 273 | ||
274 | **Rational:** less typing in the common case, uniformity. | 274 | **Rationale:** less typing in the common case, uniformity. |
275 | 275 | ||
276 | ## Functions Over Objects | 276 | ## Functions Over Objects |
277 | 277 | ||
@@ -327,7 +327,7 @@ impl ThingDoer { | |||
327 | } | 327 | } |
328 | ``` | 328 | ``` |
329 | 329 | ||
330 | **Rational:** not bothering the caller with irrelevant details, not mixing user API with implementor API. | 330 | **Rationale:** not bothering the caller with irrelevant details, not mixing user API with implementor API. |
331 | 331 | ||
332 | ## Avoid Monomorphization | 332 | ## Avoid Monomorphization |
333 | 333 | ||
@@ -360,7 +360,7 @@ fn frbonicate(f: impl AsRef<Path>) { | |||
360 | } | 360 | } |
361 | ``` | 361 | ``` |
362 | 362 | ||
363 | **Rational:** Rust uses monomorphization to compile generic code, meaning that for each instantiation of a generic functions with concrete types, the function is compiled afresh, *per crate*. | 363 | **Rationale:** Rust uses monomorphization to compile generic code, meaning that for each instantiation of a generic functions with concrete types, the function is compiled afresh, *per crate*. |
364 | This allows for exceptionally good performance, but leads to increased compile times. | 364 | This allows for exceptionally good performance, but leads to increased compile times. |
365 | Runtime performance obeys 80%/20% rule -- only a small fraction of code is hot. | 365 | Runtime performance obeys 80%/20% rule -- only a small fraction of code is hot. |
366 | Compile time **does not** obey this rule -- all code has to be compiled. | 366 | Compile time **does not** obey this rule -- all code has to be compiled. |
@@ -389,7 +389,7 @@ if words.len() != 2 { | |||
389 | } | 389 | } |
390 | ``` | 390 | ``` |
391 | 391 | ||
392 | **Rational:** not allocating is almost often faster. | 392 | **Rationale:** not allocating is almost often faster. |
393 | 393 | ||
394 | ## Push Allocations to the Call Site | 394 | ## Push Allocations to the Call Site |
395 | 395 | ||
@@ -408,14 +408,14 @@ fn frobnicate(s: &str) { | |||
408 | } | 408 | } |
409 | ``` | 409 | ``` |
410 | 410 | ||
411 | **Rational:** reveals the costs. | 411 | **Rationale:** reveals the costs. |
412 | It is also more efficient when the caller already owns the allocation. | 412 | It is also more efficient when the caller already owns the allocation. |
413 | 413 | ||
414 | ## Collection types | 414 | ## Collection types |
415 | 415 | ||
416 | Prefer `rustc_hash::FxHashMap` and `rustc_hash::FxHashSet` instead of the ones in `std::collections`. | 416 | Prefer `rustc_hash::FxHashMap` and `rustc_hash::FxHashSet` instead of the ones in `std::collections`. |
417 | 417 | ||
418 | **Rational:** they use a hasher that's significantly faster and using them consistently will reduce code size by some small amount. | 418 | **Rationale:** they use a hasher that's significantly faster and using them consistently will reduce code size by some small amount. |
419 | 419 | ||
420 | # Style | 420 | # Style |
421 | 421 | ||
@@ -445,7 +445,7 @@ use crate::{} | |||
445 | use super::{} | 445 | use super::{} |
446 | ``` | 446 | ``` |
447 | 447 | ||
448 | **Rational:** consistency. | 448 | **Rationale:** consistency. |
449 | Reading order is important for new contributors. | 449 | Reading order is important for new contributors. |
450 | Grouping by crate allows to spot unwanted dependencies easier. | 450 | Grouping by crate allows to spot unwanted dependencies easier. |
451 | 451 | ||
@@ -466,7 +466,7 @@ use syntax::ast::Struct; | |||
466 | fn frobnicate(func: Function, strukt: Struct) {} | 466 | fn frobnicate(func: Function, strukt: Struct) {} |
467 | ``` | 467 | ``` |
468 | 468 | ||
469 | **Rational:** avoids name clashes, makes the layer clear at a glance. | 469 | **Rationale:** avoids name clashes, makes the layer clear at a glance. |
470 | 470 | ||
471 | When implementing traits from `std::fmt` or `std::ops`, import the module: | 471 | When implementing traits from `std::fmt` or `std::ops`, import the module: |
472 | 472 | ||
@@ -492,14 +492,14 @@ impl Deref for Widget { | |||
492 | } | 492 | } |
493 | ``` | 493 | ``` |
494 | 494 | ||
495 | **Rational:** overall, less typing. | 495 | **Rationale:** overall, less typing. |
496 | Makes it clear that a trait is implemented, rather than used. | 496 | Makes it clear that a trait is implemented, rather than used. |
497 | 497 | ||
498 | Avoid local `use MyEnum::*` imports. | 498 | Avoid local `use MyEnum::*` imports. |
499 | **Rational:** consistency. | 499 | **Rationale:** consistency. |
500 | 500 | ||
501 | Prefer `use crate::foo::bar` to `use super::bar` or `use self::bar::baz`. | 501 | Prefer `use crate::foo::bar` to `use super::bar` or `use self::bar::baz`. |
502 | **Rational:** consistency, this is the style which works in all cases. | 502 | **Rationale:** consistency, this is the style which works in all cases. |
503 | 503 | ||
504 | ## Order of Items | 504 | ## Order of Items |
505 | 505 | ||
@@ -570,7 +570,7 @@ impl Parent { | |||
570 | } | 570 | } |
571 | ``` | 571 | ``` |
572 | 572 | ||
573 | **Rational:** easier to get the sense of the API by visually scanning the file. | 573 | **Rationale:** easier to get the sense of the API by visually scanning the file. |
574 | If function bodies are folded in the editor, the source code should read as documentation for the public API. | 574 | If function bodies are folded in the editor, the source code should read as documentation for the public API. |
575 | 575 | ||
576 | ## Variable Naming | 576 | ## Variable Naming |
@@ -626,7 +626,7 @@ fn foo() -> Option<Bar> { | |||
626 | } | 626 | } |
627 | ``` | 627 | ``` |
628 | 628 | ||
629 | **Rational:** reduce congnitive stack usage. | 629 | **Rationale:** reduce congnitive stack usage. |
630 | 630 | ||
631 | ## Comparisons | 631 | ## Comparisons |
632 | 632 | ||
@@ -640,7 +640,7 @@ assert!(lo <= x && x <= hi); | |||
640 | assert!(x >= lo && x <= hi>); | 640 | assert!(x >= lo && x <= hi>); |
641 | ``` | 641 | ``` |
642 | 642 | ||
643 | **Rational:** Less-then comparisons are more intuitive, they correspond spatially to [real line](https://en.wikipedia.org/wiki/Real_line). | 643 | **Rationale:** Less-then comparisons are more intuitive, they correspond spatially to [real line](https://en.wikipedia.org/wiki/Real_line). |
644 | 644 | ||
645 | 645 | ||
646 | ## Documentation | 646 | ## Documentation |
@@ -648,4 +648,4 @@ assert!(x >= lo && x <= hi>); | |||
648 | For `.md` and `.adoc` files, prefer a sentence-per-line format, don't wrap lines. | 648 | For `.md` and `.adoc` files, prefer a sentence-per-line format, don't wrap lines. |
649 | If the line is too long, you want to split the sentence in two :-) | 649 | If the line is too long, you want to split the sentence in two :-) |
650 | 650 | ||
651 | **Rational:** much easier to edit the text and read the diff. | 651 | **Rationale:** much easier to edit the text and read the diff. |