aboutsummaryrefslogtreecommitdiff
path: root/docs/dev/style.md
diff options
context:
space:
mode:
authorDmitry <[email protected]>2020-08-14 19:32:05 +0100
committerDmitry <[email protected]>2020-08-14 19:32:05 +0100
commit178c3e135a2a249692f7784712492e7884ae0c00 (patch)
treeac6b769dbf7162150caa0c1624786a4dd79ff3be /docs/dev/style.md
parent06ff8e6c760ff05f10e868b5d1f9d79e42fbb49c (diff)
parentc2594daf2974dbd4ce3d9b7ec72481764abaceb5 (diff)
Merge remote-tracking branch 'origin/master'
Diffstat (limited to 'docs/dev/style.md')
-rw-r--r--docs/dev/style.md22
1 files changed, 11 insertions, 11 deletions
diff --git a/docs/dev/style.md b/docs/dev/style.md
index 1c68f5702..963a6d73d 100644
--- a/docs/dev/style.md
+++ b/docs/dev/style.md
@@ -65,7 +65,7 @@ There are many benefits to this:
65It also makes sense to format snippets more compactly (for example, by placing enum definitions like `enum E { Foo, Bar }` on a single line), 65It also makes sense to format snippets more compactly (for example, by placing enum definitions like `enum E { Foo, Bar }` on a single line),
66as long as they are still readable. 66as long as they are still readable.
67 67
68## Order of Imports 68# Order of Imports
69 69
70Separate import groups with blank lines. 70Separate import groups with blank lines.
71Use one `use` per crate. 71Use one `use` per crate.
@@ -91,19 +91,19 @@ use super::{}
91Module declarations come before the imports. 91Module declarations come before the imports.
92Order them in "suggested reading order" for a person new to the code base. 92Order them in "suggested reading order" for a person new to the code base.
93 93
94## Import Style 94# Import Style
95 95
96Qualify items from `hir` and `ast`. 96Qualify items from `hir` and `ast`.
97 97
98```rust 98```rust
99// Good 99// Good
100use ra_syntax::ast; 100use syntax::ast;
101 101
102fn frobnicate(func: hir::Function, strukt: ast::StructDef) {} 102fn frobnicate(func: hir::Function, strukt: ast::StructDef) {}
103 103
104// Not as good 104// Not as good
105use hir::Function; 105use hir::Function;
106use ra_syntax::ast::StructDef; 106use syntax::ast::StructDef;
107 107
108fn frobnicate(func: Function, strukt: StructDef) {} 108fn frobnicate(func: Function, strukt: StructDef) {}
109``` 109```
@@ -112,7 +112,7 @@ Avoid local `use MyEnum::*` imports.
112 112
113Prefer `use crate::foo::bar` to `use super::bar`. 113Prefer `use crate::foo::bar` to `use super::bar`.
114 114
115## Order of Items 115# Order of Items
116 116
117Optimize for the reader who sees the file for the first time, and wants to get a general idea about what's going on. 117Optimize for the reader who sees the file for the first time, and wants to get a general idea about what's going on.
118People read things from top to bottom, so place most important things first. 118People read things from top to bottom, so place most important things first.
@@ -143,7 +143,7 @@ struct Foo {
143} 143}
144``` 144```
145 145
146## Variable Naming 146# Variable Naming
147 147
148Use boring and long names for local variables ([yay code completion](https://github.com/rust-analyzer/rust-analyzer/pull/4162#discussion_r417130973)). 148Use boring and long names for local variables ([yay code completion](https://github.com/rust-analyzer/rust-analyzer/pull/4162#discussion_r417130973)).
149The default name is a lowercased name of the type: `global_state: GlobalState`. 149The default name is a lowercased name of the type: `global_state: GlobalState`.
@@ -151,12 +151,12 @@ Avoid ad-hoc acronyms and contractions, but use the ones that exist consistently
151The default name for "result of the function" local variable is `res`. 151The default name for "result of the function" local variable is `res`.
152The default name for "I don't really care about the name" variable is `it`. 152The default name for "I don't really care about the name" variable is `it`.
153 153
154## Collection types 154# Collection types
155 155
156Prefer `rustc_hash::FxHashMap` and `rustc_hash::FxHashSet` instead of the ones in `std::collections`. 156Prefer `rustc_hash::FxHashMap` and `rustc_hash::FxHashSet` instead of the ones in `std::collections`.
157They use a hasher that's slightly faster and using them consistently will reduce code size by some small amount. 157They use a hasher that's slightly faster and using them consistently will reduce code size by some small amount.
158 158
159## Preconditions 159# Preconditions
160 160
161Express function preconditions in types and force the caller to provide them (rather than checking in callee): 161Express function preconditions in types and force the caller to provide them (rather than checking in callee):
162 162
@@ -176,7 +176,7 @@ fn frobnicate(walrus: Option<Walrus>) {
176} 176}
177``` 177```
178 178
179## Premature Pessimization 179# Premature Pessimization
180 180
181Avoid writing code which is slower than it needs to be. 181Avoid writing code which is slower than it needs to be.
182Don't allocate a `Vec` where an iterator would do, don't allocate strings needlessly. 182Don't allocate a `Vec` where an iterator would do, don't allocate strings needlessly.
@@ -197,12 +197,12 @@ if words.len() != 2 {
197} 197}
198``` 198```
199 199
200## Documentation 200# Documentation
201 201
202For `.md` and `.adoc` files, prefer a sentence-per-line format, don't wrap lines. 202For `.md` and `.adoc` files, prefer a sentence-per-line format, don't wrap lines.
203If the line is too long, you want to split the sentence in two :-) 203If the line is too long, you want to split the sentence in two :-)
204 204
205## Commit Style 205# Commit Style
206 206
207We don't have specific rules around git history hygiene. 207We don't have specific rules around git history hygiene.
208Maintaining clean git history is encouraged, but not enforced. 208Maintaining clean git history is encouraged, but not enforced.