aboutsummaryrefslogtreecommitdiff
path: root/docs
diff options
context:
space:
mode:
Diffstat (limited to 'docs')
-rw-r--r--docs/dev/style.md41
1 files changed, 40 insertions, 1 deletions
diff --git a/docs/dev/style.md b/docs/dev/style.md
index 1b1c24b1e..c594946be 100644
--- a/docs/dev/style.md
+++ b/docs/dev/style.md
@@ -806,9 +806,48 @@ if let Some(expected_type) = ctx.expected_type.as_ref() {
806} 806}
807``` 807```
808 808
809**Rational:** `match` is almost always more compact. 809**Rationale:** `match` is almost always more compact.
810The `else` branch can get a more precise pattern: `None` or `Err(_)` instead of `_`. 810The `else` branch can get a more precise pattern: `None` or `Err(_)` instead of `_`.
811 811
812## Helper Functions
813
814Avoid creating singe-use helper functions:
815
816```rust
817// GOOD
818let buf = {
819 let mut buf = get_empty_buf(&mut arena);
820 buf.add_item(item);
821 buf
822};
823
824// BAD
825
826let buf = prepare_buf(&mut arena, item);
827
828...
829
830fn prepare_buf(arena: &mut Arena, item: Item) -> ItemBuf {
831 let mut res = get_empty_buf(&mut arena);
832 res.add_item(item);
833 res
834}
835```
836
837Exception: if you want to make use of `return` or `?`.
838
839**Rationale:** single-use functions change frequently, adding or removing parameters adds churn.
840A block serves just as well to delineate a bit of logic, but has access to all the context.
841Re-using originally single-purpose function often leads to bad coupling.
842
843## Helper Variables
844
845Introduce helper variables freely, especially for multiline conditions.
846
847**Rationale:** like blocks, single-use variables are a cognitively cheap abstraction, as they have access to all the context.
848Extra variables help during debugging, they make it easy to print/view important intermediate results.
849Giving a name to a condition in `if` expression often improves clarity and leads to a nicer formatted code.
850
812## Token names 851## Token names
813 852
814Use `T![foo]` instead of `SyntaxKind::FOO_KW`. 853Use `T![foo]` instead of `SyntaxKind::FOO_KW`.