Merge pull request Rust-Coding-Guidelines#10 from PeterWrighten/main

Update: 3.9 FUN-D && Contents

Author: ZhangHanDong

src/safe-guides/coding_practice/async-await.md

@@ -1 +1 @@
-# 异步编程
+# Async 

src/safe-guides/coding_practice/cargo.md

@@ -1 +1 @@
-# 包管理
+# Cargo package management

src/safe-guides/coding_practice/fn-design.md

@@ -1 +1 @@
-# 函数设计
+# Function Design

src/safe-guides/coding_practice/fn-design/G.FUD.01.md

@@ -1 +1,51 @@
 # G.FUD.01 Less than 5 function parameters
+
+**[Level] Advice**
+
+**[Description]**
+
+In order to improve readability of code, it's better to set less than 5 function's parameters.
+
+
+**[Bad Case]**
+
+```rust
+struct Color;
+// Not Good
+fn foo(x: f32, y: f32, name: &str, c: Color, w: u32, h: u32, a: u32, b: u32) {
+    // ..
+}
+```
+
+**[Good Case]**
+
+Refine function's parameters as possible.
+
+```rust
+struct Color;
+// Good: use const generic here to receive multiple u32 typed parameters afterward.
+// use tuple to refine 2~3 parameters as one.
+fn foo<T, const N: usize>(x: (f32, f32), name: &str, c: Color, last: [T;N]) {
+    ;
+}
+
+fn main() {
+    let arr = [1u32, 2u32];
+    foo((1.0f32, 2.0f32), "hello", Color, arr);
+    let arr = [1.0f32, 2.0f32, 3.0f32];
+    foo((1.0f32, 2.0f32), "hello", Color, arr);
+}
+```
+
+**[Lint Check]**
+
+| lint name | Clippy check | Rustc Check | Lint Group | level |
+| --------- | ------------ | ----------- | ---------- | ----- |
+| [too_many_arguments](https://rust-lang.github.io/rust-clippy/master/#too_many_arguments) | yes | no | complexity | warn |
+
+This lint corresponds to the following configuration of `clippy.toml`:
+
+```toml
+# less than 5 parameters
+too-many-arguments-threshold=5
+```

src/safe-guides/coding_practice/fn-design/G.FUD.02.md

@@ -1 +1,44 @@
 # G.FUD.02 Should input as reference if parameter derives `Copy` and its value inputed by-value is a big number
+
+**[Level] Advice**
+
+**[Description]**
+
+By-value inputed parameters may emerge unnecessary `memcpy`, which could kill performance.
+
+**[Bad Case]**
+
+```rust
+#![warn(clippy::large_types_passed_by_value)]
+
+#[derive(Clone, Copy)]
+struct TooLarge([u8; 2048]);
+
+// Not Good
+fn foo(v: TooLarge) {}
+```
+
+**[Good Case]**
+
+```rust
+#![warn(clippy::large_types_passed_by_value)]
+
+#[derive(Clone, Copy)]
+struct TooLarge([u8; 2048]);
+
+// Good
+fn foo(v: &TooLarge) {}
+```
+
+**[Lint Check]**
+
+| lint name | Clippy check | Rustc check | Lint Group | Level |
+| --------- | ------------ | ----------- | ---------- | ----- |
+| [large_types_passed_by_value](https://rust-lang.github.io/rust-clippy/master/#large_types_passed_by_value) | yes | no | pedanic | allow |
+
+This lint corresponds to the following configuration of `clippy.toml`
+
+```toml
+# if function is an exported api, then the lint would not be triggered, which aims to prevent devastated change for api. the default is true.
+avoid-breaking-exported-api=true
+```

src/safe-guides/coding_practice/fn-design/P.FUD.01.md

@@ -1,11 +1,13 @@
 # P.FUD.01 Should rebind variables which pass into closure
 
 **[Description]**
+
 By default, closure captures environment variables with `borrow`, or it is also allowed to pass environment variables into closure with `move` keyword.
 
 It is more readable to rebind and regroup these variables which pass into closure.
 
 **[Bad Case]**
+
 ```rust
 use std::rc::Rc;
 let num1 = Rc::new(1);
@@ -23,6 +25,7 @@ let closure = {
 
 
 **[Good Case]**
+
 ```rust 
 use std::rc::Rc;
 

src/safe-guides/coding_practice/fn-design/P.FUD.02.md

@@ -1,11 +1,13 @@
 # P.FUD.02 Don't Use `return` for return value
 
 **[Description]**
+
 In such that function would automatically return the value of last expression in Rust, it is not required to use `return` explicitly.
 
 Only when it is necessary to return a value in procedure of function, should use `return` explicitly.
 
 **[Bad Case]**
+
 ```rust
 fn foo(x: usize) -> usize {
     if x < 42 {
@@ -14,7 +16,9 @@ fn foo(x: usize) -> usize {
     return x + 1; // Not Good
 }
 ```
+
 **[Good Case]**
+
 ```rust
 fn foo(x: usize) -> usize {
     if x < 42 {