aboutsummaryrefslogtreecommitdiff
path: root/docs/dev/style.md
diff options
context:
space:
mode:
Diffstat (limited to 'docs/dev/style.md')
-rw-r--r--docs/dev/style.md46
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.
53Don't use small "helper" crates (exception: `itertools` is allowed). 53Don't use small "helper" crates (exception: `itertools` is allowed).
54If there's some general reusable bit of code you need, consider adding it to the `stdx` crate. 54If 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
57compiles, reduce the number of things which might break. 57compiles, 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
79This makes it easier to prepare a changelog. 79This 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.
82But many users read changelogs. 82But 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.
90Careful tweaking of `xtask lint` is welcome. 90Careful tweaking of `xtask lint` is welcome.
91Of course, applying Clippy suggestions is welcome as long as they indeed improve the code. 91Of 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
131There are many benefits to this: 131There 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.
161Call-site has more context, it often happens that the precondition falls out naturally or can be bubbled up higher in the stack. 161Call-site has more context, it often happens that the precondition falls out naturally or can be bubbled up higher in the stack.
162 162
163Avoid splitting precondition check and precondition use across functions: 163Avoid splitting precondition check and precondition use across functions:
@@ -195,7 +195,7 @@ fn is_string_literal(s: &str) -> bool {
195In the "Not as good" version, the precondition that `1` is a valid char boundary is checked in `is_string_literal` and used in `foo`. 195In the "Not as good" version, the precondition that `1` is a valid char boundary is checked in `is_string_literal` and used in `foo`.
196In the "Good" version, the precondition check and usage are checked in the same block, and then encoded in the types. 196In 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
200When checking a boolean precondition, prefer `if !invariant` to `if negated_invariant`: 200When 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.
245Non-local code properties degrade under change, privacy makes invariant local. 245Non-local code properties degrade under change, privacy makes invariant local.
246Borrowed own data discloses irrelevant details about origin of data. 246Borrowed own data discloses irrelevant details about origin of data.
247Irrelevant (neither right nor wrong) things obscure correctness. 247Irrelevant (neither right nor wrong) things obscure correctness.
@@ -271,7 +271,7 @@ impl Foo {
271 271
272Prefer `Default` even it has to be implemented manually. 272Prefer `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*.
364This allows for exceptionally good performance, but leads to increased compile times. 364This allows for exceptionally good performance, but leads to increased compile times.
365Runtime performance obeys 80%/20% rule -- only a small fraction of code is hot. 365Runtime performance obeys 80%/20% rule -- only a small fraction of code is hot.
366Compile time **does not** obey this rule -- all code has to be compiled. 366Compile 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.
412It is also more efficient when the caller already owns the allocation. 412It is also more efficient when the caller already owns the allocation.
413 413
414## Collection types 414## Collection types
415 415
416Prefer `rustc_hash::FxHashMap` and `rustc_hash::FxHashSet` instead of the ones in `std::collections`. 416Prefer `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::{}
445use super::{} 445use super::{}
446``` 446```
447 447
448**Rational:** consistency. 448**Rationale:** consistency.
449Reading order is important for new contributors. 449Reading order is important for new contributors.
450Grouping by crate allows to spot unwanted dependencies easier. 450Grouping by crate allows to spot unwanted dependencies easier.
451 451
@@ -466,7 +466,7 @@ use syntax::ast::Struct;
466fn frobnicate(func: Function, strukt: Struct) {} 466fn 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
471When implementing traits from `std::fmt` or `std::ops`, import the module: 471When 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.
496Makes it clear that a trait is implemented, rather than used. 496Makes it clear that a trait is implemented, rather than used.
497 497
498Avoid local `use MyEnum::*` imports. 498Avoid local `use MyEnum::*` imports.
499**Rational:** consistency. 499**Rationale:** consistency.
500 500
501Prefer `use crate::foo::bar` to `use super::bar` or `use self::bar::baz`. 501Prefer `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.
574If function bodies are folded in the editor, the source code should read as documentation for the public API. 574If 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);
640assert!(x >= lo && x <= hi>); 640assert!(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>);
648For `.md` and `.adoc` files, prefer a sentence-per-line format, don't wrap lines. 648For `.md` and `.adoc` files, prefer a sentence-per-line format, don't wrap lines.
649If the line is too long, you want to split the sentence in two :-) 649If 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.