Merge #6250

6250: Expand code order section r=matklad a=matklad

bors r+
🤖

Co-authored-by: Aleksey Kladov <aleksey.kladov@gmail.com>

1 files changed, 50 insertions, 11 deletions

diff --git a/docs/dev/style.md b/docs/dev/style.md
index 883a6845d91..7a64a0d228c 100644
--- a/docs/dev/style.md
+++ b/docs/dev/style.md
@@ -366,27 +366,66 @@ People read things from top to bottom, so place most important things first.
 
 Specifically, if all items except one are private, always put the non-private item on top.
 
-Put `struct`s and `enum`s first, functions and impls last.
-
-Do
-
 ```rust
 // Good
-struct Foo {
-    bars: Vec<Bar>
+pub(crate) fn frobnicate() {
+    Helper::act()
+}
+
+#[derive(Default)]
+struct Helper { stuff: i32 }
+
+impl Helper {
+    fn act(&self) {
+
+    }
+}
+
+// Not as good
+#[derive(Default)]
+struct Helper { stuff: i32 }
+
+pub(crate) fn frobnicate() {
+    Helper::act()
 }
 
-struct Bar;
+impl Helper {
+    fn act(&self) {
+
+    }
+}
 ```
 
-rather than
+If there's a mixture of private and public items, put public items first.
+If function bodies are folded in the editor, the source code should read as documentation for the public API.
+
+Put `struct`s and `enum`s first, functions and impls last. Order types declarations in top-down manner.
 
 ```rust
+// Good
+struct Parent {
+    children: Vec<Child>
+}
+
+struct Child;
+
+impl Parent {
+}
+
+impl Child {
+}
+
 // Not as good
-struct Bar;
+struct Child;
 
-struct Foo {
-    bars: Vec<Bar>
+impl Child {
+}
+
+struct Parent {
+    children: Vec<Child>
+}
+
+impl Parent {
 }
 ```