1 files changed, 13 insertions, 0 deletions

diff --git a/docs/dev/README.md b/docs/dev/README.md
index 1ce8666e3..4cb5dfaa0 100644
--- a/docs/dev/README.md
+++ b/docs/dev/README.md
@@ -236,6 +236,13 @@ struct Foo {
 }
 ```
 
+## Variable Naming
+
+We generally use boring and long names for local variables ([yay code completion](https://github.com/rust-analyzer/rust-analyzer/pull/4162#discussion_r417130973)).
+The default name is lowercased named of the type: `global_state: GlobalState`.
+Avoid ad-hoc acronyms and contractions, but use the ones that exist consistently (`db`, `ctx`, `acc`).
+The default name for "result of the function" local variable is `res`.
+
 ## Preconditions
 
 Function preconditions should generally be expressed in types and provided by the caller (rather than checked by callee):
@@ -335,6 +342,12 @@ There are two kinds of tests:
 The purpose of inline tests is not to achieve full coverage by test cases, but to explain to the reader of the code what each particular `if` and `match` is responsible for.
 If you are tempted to add a large inline test, it might be a good idea to leave only the simplest example in place, and move the test to a manual `parser/ok` test.
 
+To update test data, run with `UPDATE_EXPECTATIONS` variable:
+
+```bash
+env UPDATE_EXPECTATIONS=1 cargo qt
+```
+
 # Logging
 
 Logging is done by both rust-analyzer and VS Code, so it might be tricky to