diff options
Diffstat (limited to 'docs')
-rw-r--r-- | docs/dev/style.md | 22 |
1 files changed, 22 insertions, 0 deletions
diff --git a/docs/dev/style.md b/docs/dev/style.md index 389649398..428cee3ad 100644 --- a/docs/dev/style.md +++ b/docs/dev/style.md | |||
@@ -6,6 +6,9 @@ Our approach to "clean code" is two-fold: | |||
6 | 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. | 6 | 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. |
7 | Sending small cleanup PRs (like renaming a single local variable) is encouraged. | 7 | Sending small cleanup PRs (like renaming a single local variable) is encouraged. |
8 | 8 | ||
9 | When reviewing pull requests prefer extending this document to leaving | ||
10 | non-reusable comments on the pull request itself. | ||
11 | |||
9 | # General | 12 | # General |
10 | 13 | ||
11 | ## Scale of Changes | 14 | ## Scale of Changes |
@@ -139,6 +142,17 @@ There are many benefits to this: | |||
139 | 142 | ||
140 | Formatting ensures that you can use your editor's "number of selected characters" feature to correlate offsets with test's source code. | 143 | Formatting ensures that you can use your editor's "number of selected characters" feature to correlate offsets with test's source code. |
141 | 144 | ||
145 | ## Marked Tests | ||
146 | |||
147 | Use | ||
148 | [`mark::hit! / mark::check!`](https://github.com/rust-analyzer/rust-analyzer/blob/71fe719dd5247ed8615641d9303d7ca1aa201c2f/crates/test_utils/src/mark.rs) | ||
149 | when testing specific conditions. | ||
150 | Do not place several marks into a single test or condition. | ||
151 | Do not reuse marks between several tests. | ||
152 | |||
153 | **Rationale:** marks provide an easy way to find the canonical test for each bit of code. | ||
154 | This makes it much easier to understand. | ||
155 | |||
142 | ## Function Preconditions | 156 | ## Function Preconditions |
143 | 157 | ||
144 | Express function preconditions in types and force the caller to provide them (rather than checking in callee): | 158 | Express function preconditions in types and force the caller to provide them (rather than checking in callee): |
@@ -375,6 +389,14 @@ This allows for exceptionally good performance, but leads to increased compile t | |||
375 | Runtime performance obeys 80%/20% rule -- only a small fraction of code is hot. | 389 | Runtime performance obeys 80%/20% rule -- only a small fraction of code is hot. |
376 | Compile time **does not** obey this rule -- all code has to be compiled. | 390 | Compile time **does not** obey this rule -- all code has to be compiled. |
377 | 391 | ||
392 | ## Appropriate String Types | ||
393 | |||
394 | When interfacing with OS APIs, use `OsString`, even if the original source of data is utf-8 encoded. | ||
395 | **Rationale:** cleanly delineates the boundary when the data goes into the OS-land. | ||
396 | |||
397 | Use `AbsPathBuf` and `AbsPath` over `std::Path`. | ||
398 | **Rationale:** rust-analyzer is a long-lived process which handles several projects at the same time. | ||
399 | It is important not to leak cwd by accident. | ||
378 | 400 | ||
379 | # Premature Pessimization | 401 | # Premature Pessimization |
380 | 402 | ||