2 files changed, 61 insertions, 1 deletions

diff --git a/docs/dev/README.md b/docs/dev/README.md
index dd2bfc493..24197b332 100644
--- a/docs/dev/README.md
+++ b/docs/dev/README.md
@@ -251,6 +251,9 @@ RA_PROFILE=*@3>10        // dump everything, up to depth 3, if it takes more tha
 
 In particular, I have `export RA_PROFILE='*>10'` in my shell profile.
 
+We also have a "counting" profiler which counts number of instances of popular structs.
+It is enabled by `RA_COUNT=1`.
+
 To measure time for from-scratch analysis, use something like this:
 
 ```
diff --git a/docs/dev/style.md b/docs/dev/style.md
index 21330948b..428cee3ad 100644
--- a/docs/dev/style.md
+++ b/docs/dev/style.md
@@ -6,6 +6,9 @@ Our approach to "clean code" is two-fold:
 It is explicitly OK for a reviewer to flag only some nits in the PR, and then send a follow-up cleanup PR for things which are easier to explain by example, cc-ing the original author.
 Sending small cleanup PRs (like renaming a single local variable) is encouraged.
 
+When reviewing pull requests prefer extending this document to leaving
+non-reusable comments on the pull request itself.
+
 # General
 
 ## Scale of Changes
@@ -139,6 +142,17 @@ There are many benefits to this:
 
 Formatting ensures that you can use your editor's "number of selected characters" feature to correlate offsets with test's source code.
 
+## Marked Tests
+
+Use
+[`mark::hit! / mark::check!`](https://github.com/rust-analyzer/rust-analyzer/blob/71fe719dd5247ed8615641d9303d7ca1aa201c2f/crates/test_utils/src/mark.rs)
+when testing specific conditions.
+Do not place several marks into a single test or condition.
+Do not reuse marks between several tests.
+
+**Rationale:** marks provide an easy way to find the canonical test for each bit of code.
+This makes it much easier to understand.
+
 ## Function Preconditions
 
 Express function preconditions in types and force the caller to provide them (rather than checking in callee):
@@ -280,6 +294,9 @@ Prefer `Default` even it has to be implemented manually.
 
 **Rationale:** less typing in the common case, uniformity.
 
+Use `Vec::new` rather than `vec![]`. **Rationale:** uniformity, strength
+reduction.
+
 ## Functions Over Objects
 
 Avoid creating "doer" objects.
@@ -372,6 +389,14 @@ This allows for exceptionally good performance, but leads to increased compile t
 Runtime performance obeys 80%/20% rule -- only a small fraction of code is hot.
 Compile time **does not** obey this rule -- all code has to be compiled.
 
+## Appropriate String Types
+
+When interfacing with OS APIs, use `OsString`, even if the original source of data is utf-8 encoded.
+**Rationale:** cleanly delineates the boundary when the data goes into the OS-land.
+
+Use `AbsPathBuf` and `AbsPath` over `std::Path`.
+**Rationale:** rust-analyzer is a long-lived process which handles several projects at the same time.
+It is important not to leak cwd by accident.
 
 # Premature Pessimization
 
@@ -418,12 +443,44 @@ fn frobnicate(s: &str) {
 **Rationale:** reveals the costs.
 It is also more efficient when the caller already owns the allocation.
 
-## Collection types
+## Collection Types
 
 Prefer `rustc_hash::FxHashMap` and `rustc_hash::FxHashSet` instead of the ones in `std::collections`.
 
 **Rationale:** they use a hasher that's significantly faster and using them consistently will reduce code size by some small amount.
 
+## Avoid Intermediate Collections
+
+When writing a recursive function to compute a sets of things, use an accumulator parameter instead of returning a fresh collection.
+Accumulator goes first in the list of arguments.
+
+```rust
+// GOOD
+pub fn reachable_nodes(node: Node) -> FxHashSet<Node> {
+    let mut res = FxHashSet::default();
+    go(&mut res, node);
+    res
+}
+fn go(acc: &mut FxHashSet<Node>, node: Node) {
+    acc.insert(node);
+    for n in node.neighbors() {
+        go(acc, n);
+    }
+}
+
+// BAD
+pub fn reachable_nodes(node: Node) -> FxHashSet<Node> {
+    let mut res = FxHashSet::default();
+    res.insert(node);
+    for n in node.neighbors() {
+        res.extend(reachable_nodes(n));
+    }
+    res
+}
+```
+
+**Rational:** re-use allocations, accumulator style is more concise for complex cases.
+
 # Style
 
 ## Order of Imports