diff options
-rw-r--r-- | docs/dev/README.md | 5 | ||||
-rw-r--r-- | docs/dev/style.md | 18 |
2 files changed, 14 insertions, 9 deletions
diff --git a/docs/dev/README.md b/docs/dev/README.md index ad18217f1..36edddc70 100644 --- a/docs/dev/README.md +++ b/docs/dev/README.md | |||
@@ -165,6 +165,11 @@ In general, API is centered around UI concerns -- the result of the call is what | |||
165 | The results are 100% Rust specific though. | 165 | The results are 100% Rust specific though. |
166 | Shout outs to LSP developers for popularizing the idea that "UI" is a good place to draw a boundary at. | 166 | Shout outs to LSP developers for popularizing the idea that "UI" is a good place to draw a boundary at. |
167 | 167 | ||
168 | ## CI | ||
169 | |||
170 | CI does not test rust-analyzer, CI is a core part of rust-analyzer, and is maintained with above average standard of quality. | ||
171 | CI is reproducible -- it can only be broken by changes to files in this repository, any dependence on externalities is a bug. | ||
172 | |||
168 | # Code Style & Review Process | 173 | # Code Style & Review Process |
169 | 174 | ||
170 | Do see [./style.md](./style.md). | 175 | Do see [./style.md](./style.md). |
diff --git a/docs/dev/style.md b/docs/dev/style.md index 3bbab6da9..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,7 +91,7 @@ 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 | ||
@@ -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. |