From 0650f77dd9defaf352f81c5ee4ee73a1eae942b7 Mon Sep 17 00:00:00 2001 From: Aleksey Kladov 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/dev/style.md') 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