diff options
author | Dmitry <[email protected]> | 2020-08-14 19:32:05 +0100 |
---|---|---|
committer | Dmitry <[email protected]> | 2020-08-14 19:32:05 +0100 |
commit | 178c3e135a2a249692f7784712492e7884ae0c00 (patch) | |
tree | ac6b769dbf7162150caa0c1624786a4dd79ff3be /docs/dev/style.md | |
parent | 06ff8e6c760ff05f10e868b5d1f9d79e42fbb49c (diff) | |
parent | c2594daf2974dbd4ce3d9b7ec72481764abaceb5 (diff) |
Merge remote-tracking branch 'origin/master'
Diffstat (limited to 'docs/dev/style.md')
-rw-r--r-- | docs/dev/style.md | 22 |
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: | |||
65 | It also makes sense to format snippets more compactly (for example, by placing enum definitions like `enum E { Foo, Bar }` on a single line), | 65 | It also makes sense to format snippets more compactly (for example, by placing enum definitions like `enum E { Foo, Bar }` on a single line), |
66 | as long as they are still readable. | 66 | as long as they are still readable. |
67 | 67 | ||
68 | ## Order of Imports | 68 | # Order of Imports |
69 | 69 | ||
70 | Separate import groups with blank lines. | 70 | Separate import groups with blank lines. |
71 | Use one `use` per crate. | 71 | Use one `use` per crate. |
@@ -91,19 +91,19 @@ use super::{} | |||
91 | Module declarations come before the imports. | 91 | Module declarations come before the imports. |
92 | Order them in "suggested reading order" for a person new to the code base. | 92 | Order them in "suggested reading order" for a person new to the code base. |
93 | 93 | ||
94 | ## Import Style | 94 | # Import Style |
95 | 95 | ||
96 | Qualify items from `hir` and `ast`. | 96 | Qualify items from `hir` and `ast`. |
97 | 97 | ||
98 | ```rust | 98 | ```rust |
99 | // Good | 99 | // Good |
100 | use ra_syntax::ast; | 100 | use syntax::ast; |
101 | 101 | ||
102 | fn frobnicate(func: hir::Function, strukt: ast::StructDef) {} | 102 | fn frobnicate(func: hir::Function, strukt: ast::StructDef) {} |
103 | 103 | ||
104 | // Not as good | 104 | // Not as good |
105 | use hir::Function; | 105 | use hir::Function; |
106 | use ra_syntax::ast::StructDef; | 106 | use syntax::ast::StructDef; |
107 | 107 | ||
108 | fn frobnicate(func: Function, strukt: StructDef) {} | 108 | fn frobnicate(func: Function, strukt: StructDef) {} |
109 | ``` | 109 | ``` |
@@ -112,7 +112,7 @@ Avoid local `use MyEnum::*` imports. | |||
112 | 112 | ||
113 | Prefer `use crate::foo::bar` to `use super::bar`. | 113 | Prefer `use crate::foo::bar` to `use super::bar`. |
114 | 114 | ||
115 | ## Order of Items | 115 | # Order of Items |
116 | 116 | ||
117 | Optimize for the reader who sees the file for the first time, and wants to get a general idea about what's going on. | 117 | Optimize for the reader who sees the file for the first time, and wants to get a general idea about what's going on. |
118 | People read things from top to bottom, so place most important things first. | 118 | People 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 | ||
148 | Use boring and long names for local variables ([yay code completion](https://github.com/rust-analyzer/rust-analyzer/pull/4162#discussion_r417130973)). | 148 | Use boring and long names for local variables ([yay code completion](https://github.com/rust-analyzer/rust-analyzer/pull/4162#discussion_r417130973)). |
149 | The default name is a lowercased name of the type: `global_state: GlobalState`. | 149 | The 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 | |||
151 | The default name for "result of the function" local variable is `res`. | 151 | The default name for "result of the function" local variable is `res`. |
152 | The default name for "I don't really care about the name" variable is `it`. | 152 | The default name for "I don't really care about the name" variable is `it`. |
153 | 153 | ||
154 | ## Collection types | 154 | # Collection types |
155 | 155 | ||
156 | Prefer `rustc_hash::FxHashMap` and `rustc_hash::FxHashSet` instead of the ones in `std::collections`. | 156 | Prefer `rustc_hash::FxHashMap` and `rustc_hash::FxHashSet` instead of the ones in `std::collections`. |
157 | They use a hasher that's slightly faster and using them consistently will reduce code size by some small amount. | 157 | They 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 | ||
161 | Express function preconditions in types and force the caller to provide them (rather than checking in callee): | 161 | Express 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 | ||
181 | Avoid writing code which is slower than it needs to be. | 181 | Avoid writing code which is slower than it needs to be. |
182 | Don't allocate a `Vec` where an iterator would do, don't allocate strings needlessly. | 182 | Don'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 | ||
202 | For `.md` and `.adoc` files, prefer a sentence-per-line format, don't wrap lines. | 202 | For `.md` and `.adoc` files, prefer a sentence-per-line format, don't wrap lines. |
203 | If the line is too long, you want to split the sentence in two :-) | 203 | If the line is too long, you want to split the sentence in two :-) |
204 | 204 | ||
205 | ## Commit Style | 205 | # Commit Style |
206 | 206 | ||
207 | We don't have specific rules around git history hygiene. | 207 | We don't have specific rules around git history hygiene. |
208 | Maintaining clean git history is encouraged, but not enforced. | 208 | Maintaining clean git history is encouraged, but not enforced. |