aboutsummaryrefslogtreecommitdiff
path: root/docs
diff options
context:
space:
mode:
Diffstat (limited to 'docs')
-rw-r--r--docs/dev/README.md43
1 files changed, 32 insertions, 11 deletions
diff --git a/docs/dev/README.md b/docs/dev/README.md
index ef5ffbf59..1ce8666e3 100644
--- a/docs/dev/README.md
+++ b/docs/dev/README.md
@@ -219,7 +219,7 @@ Do
219```rust 219```rust
220// Good 220// Good
221struct Foo { 221struct Foo {
222 bars: Vec<Bar> 222 bars: Vec<Bar>
223} 223}
224 224
225struct Bar; 225struct Bar;
@@ -232,15 +232,10 @@ rather than
232struct Bar; 232struct Bar;
233 233
234struct Foo { 234struct Foo {
235 bars: Vec<Bar> 235 bars: Vec<Bar>
236} 236}
237``` 237```
238 238
239## Documentation
240
241For `.md` and `.adoc` files, prefer a sentence-per-line format, don't wrap lines.
242If the line is too long, you want to split the sentence in two :-)
243
244## Preconditions 239## Preconditions
245 240
246Function preconditions should generally be expressed in types and provided by the caller (rather than checked by callee): 241Function preconditions should generally be expressed in types and provided by the caller (rather than checked by callee):
@@ -248,19 +243,45 @@ Function preconditions should generally be expressed in types and provided by th
248```rust 243```rust
249// Good 244// Good
250fn frbonicate(walrus: Walrus) { 245fn frbonicate(walrus: Walrus) {
251 ... 246 ...
252} 247}
253 248
254// Not as good 249// Not as good
255fn frobnicate(walrus: Option<Walrus>) { 250fn frobnicate(walrus: Option<Walrus>) {
256 let walrus = match walrus { 251 let walrus = match walrus {
252 Some(it) => it,
253 None => return,
254 };
255 ...
256}
257```
258
259## Premature Pessimization
260
261While we don't specifically optimize code yet, avoid writing the code which is slower than it needs to be.
262Don't allocate a `Vec` were an iterator would do, don't allocate strings needlessly.
263
264```rust
265// Good
266use itertools::Itertools;
267
268let (first_word, second_word) = match text.split_ascii_whitespace().collect_tuple() {
257 Some(it) => it, 269 Some(it) => it,
258 None => return, 270 None => return,
259 }; 271}
260 ... 272
273// Not as good
274let words = text.split_ascii_whitespace().collect::<Vec<_>>();
275if words.len() != 2 {
276 return
261} 277}
262``` 278```
263 279
280## Documentation
281
282For `.md` and `.adoc` files, prefer a sentence-per-line format, don't wrap lines.
283If the line is too long, you want to split the sentence in two :-)
284
264## Commit Style 285## Commit Style
265 286
266We don't have specific rules around git history hygiene. 287We don't have specific rules around git history hygiene.