aboutsummaryrefslogtreecommitdiff
path: root/docs
diff options
context:
space:
mode:
Diffstat (limited to 'docs')
-rw-r--r--docs/dev/style.md22
1 files changed, 22 insertions, 0 deletions
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() {
951 951
952## Documentation 952## Documentation
953 953
954Style inline code comments as proper sentences.
955Start with a capital letter, end with a dot.
956
957```rust
958// GOOD
959
960// Only simple single segment paths are allowed.
961MergeBehavior::Last => {
962 tree.use_tree_list().is_none() && tree.path().map(path_len) <= Some(1)
963}
964
965// BAD
966
967// only simple single segment paths are allowed
968MergeBehavior::Last => {
969 tree.use_tree_list().is_none() && tree.path().map(path_len) <= Some(1)
970}
971```
972
973**Rationale:** writing a sentence (or maybe even a paragraph) rather just "a comment" creates a more appropriate frame of mind.
974It tricks you into writing down more of the context you keep in your head while coding.
975
954For `.md` and `.adoc` files, prefer a sentence-per-line format, don't wrap lines. 976For `.md` and `.adoc` files, prefer a sentence-per-line format, don't wrap lines.
955If the line is too long, you want to split the sentence in two :-) 977If the line is too long, you want to split the sentence in two :-)
956 978