From 0650f77dd9defaf352f81c5ee4ee73a1eae942b7 Mon Sep 17 00:00:00 2001
From: Aleksey Kladov <aleksey.kladov@gmail.com>
Date: Mon, 10 May 2021 19:04:41 +0300
Subject: internal: remove one more immutable tree

---
 docs/dev/style.md | 22 ++++++++++++++++++++++
 1 file changed, 22 insertions(+)

(limited to 'docs')

diff --git a/docs/dev/style.md b/docs/dev/style.md
index 9b0ddec66..f22b69768 100644
--- a/docs/dev/style.md
+++ b/docs/dev/style.md
@@ -951,6 +951,28 @@ match p.current() {
 
 ## Documentation
 
+Style inline code comments as proper sentences.
+Start with a capital letter, end with a dot.
+
+```rust
+// GOOD
+
+// Only simple single segment paths are allowed.
+MergeBehavior::Last => {
+    tree.use_tree_list().is_none() && tree.path().map(path_len) <= Some(1)
+}
+
+// BAD
+
+// only simple single segment paths are allowed
+MergeBehavior::Last => {
+    tree.use_tree_list().is_none() && tree.path().map(path_len) <= Some(1)
+}
+```
+
+**Rationale:** writing a sentence (or maybe even a paragraph) rather just "a comment" creates a more appropriate frame of mind.
+It tricks you into writing down more of the context you keep in your head while coding.
+
 For `.md` and `.adoc` files, prefer a sentence-per-line format, don't wrap lines.
 If the line is too long, you want to split the sentence in two :-)
 
-- 
cgit v1.2.3