1 files changed, 94 insertions, 11 deletions

diff --git a/docs/dev/style.md b/docs/dev/style.md
index 59067d234..7a64a0d22 100644
--- a/docs/dev/style.md
+++ b/docs/dev/style.md
@@ -186,6 +186,31 @@ impl Person {
 }
 ```
 
+## Constructors
+
+Prefer `Default` to zero-argument `new` function
+
+```rust
+// Good
+#[derive(Default)]
+struct Foo {
+    bar: Option<Bar>
+}
+
+// Not as good
+struct Foo {
+    bar: Option<Bar>
+}
+
+impl Foo {
+    fn new() -> Foo {
+        Foo { bar: None }
+    }
+}
+```
+
+Prefer `Default` even it has to be implemented manually.
+
 ## Avoid Monomorphization
 
 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*.
@@ -223,6 +248,8 @@ fn frbonicate(f: impl AsRef<Path>) {
 
 # Premature Pessimization
 
+## Avoid Allocations
+
 Avoid writing code which is slower than it needs to be.
 Don't allocate a `Vec` where an iterator would do, don't allocate strings needlessly.
 
@@ -242,6 +269,8 @@ if words.len() != 2 {
 }
 ```
 
+## Push Allocations to the Call Site
+
 If allocation is inevitable, let the caller allocate the resource:
 
 ```rust
@@ -257,6 +286,9 @@ fn frobnicate(s: &str) {
 }
 ```
 
+This is better because it reveals the costs.
+It is also more efficient when the caller already owns the allocation.
+
 ## Collection types
 
 Prefer `rustc_hash::FxHashMap` and `rustc_hash::FxHashSet` instead of the ones in `std::collections`.
@@ -334,27 +366,66 @@ People read things from top to bottom, so place most important things first.
 
 Specifically, if all items except one are private, always put the non-private item on top.
 
-Put `struct`s and `enum`s first, functions and impls last.
-
-Do
-
 ```rust
 // Good
-struct Foo {
-    bars: Vec<Bar>
+pub(crate) fn frobnicate() {
+    Helper::act()
 }
 
-struct Bar;
+#[derive(Default)]
+struct Helper { stuff: i32 }
+
+impl Helper {
+    fn act(&self) {
+
+    }
+}
+
+// Not as good
+#[derive(Default)]
+struct Helper { stuff: i32 }
+
+pub(crate) fn frobnicate() {
+    Helper::act()
+}
+
+impl Helper {
+    fn act(&self) {
+
+    }
+}
 ```
 
-rather than
+If there's a mixture of private and public items, put public items first.
+If function bodies are folded in the editor, the source code should read as documentation for the public API.
+
+Put `struct`s and `enum`s first, functions and impls last. Order types declarations in top-down manner.
 
 ```rust
+// Good
+struct Parent {
+    children: Vec<Child>
+}
+
+struct Child;
+
+impl Parent {
+}
+
+impl Child {
+}
+
 // Not as good
-struct Bar;
+struct Child;
 
-struct Foo {
-    bars: Vec<Bar>
+impl Child {
+}
+
+struct Parent {
+    children: Vec<Child>
+}
+
+impl Parent {
 }
 ```
 
@@ -371,6 +442,18 @@ Default names:
 * `n_foo` -- number of foos
 * `foo_idx` -- index of `foo`
 
+Many names in rust-analyzer conflict with keywords.
+We use mangled names instead of `r#ident` syntax:
+
+```
+struct -> strukt
+crate  -> krate
+impl   -> imp
+trait  -> trait_
+fn     -> func
+enum   -> enum_
+mod    -> module
+```
 
 ## Early Returns