3.30 review (#103)

* V 0.3

* V0.3: modify README

* update Version to 0.3

* add code example for P.SEC.01

* modify P.SEC.01

* 3.30 review

Author: ZhangHanDong

src/safe-guides/code_style/fmt.md

@@ -2,30 +2,30 @@
 
 制定统一的编码风格，是为了提升代码的可读性，让日常代码维护和团队之间审查代码更加方便。
 
-Rust 有自动化格式化工具 rustfmt ，可以帮助开发者摆脱手工调整代码格式的工作，提升生产力。但是，rustfmt 遵循什么样的风格规范，作为开发者应该需要了解，在编写代码的时候可以主动按这样的风格编写。
+Rust 有自动化格式化工具 rustfmt ，可以帮助开发者摆脱手工调整代码格式的工作，提升生产力。但是，rustfmt 遵循什么样的风格规范，作为开发者需要了解，在编写代码的时候可以主动按这样的风格编写。
 
-说明：以下 `rustfmt` 配置中对应配置项如果 `Stable`为`No`，则表示该配置项不能用于 Stable Rust 下在 `rustfmt.toml` 中自定义，但其默认值会在`cargo fmt`时生效。在 Nightly Rust 下则都可以自定义。
+说明：
 
-在 Stable Rust 下使用未稳定配置项的方法、了解配置示例及其他全局配置项说明请参阅：[Rustfmt 配置相关说明](./../Appendix/tools/rustfmt.md) 。
+对于 `rustfmt` 中未稳定的配置项（`Stable`为`No`），则表示该配置项不能在稳定版（Stable）Rust 中更改配置，但其默认值会在`cargo fmt`时生效。在 Nightly Rust 下则都可以自定义配置。
 
-注意： 以下规则 针对 rustfmt  version 1.4.36 版本。
+如需了解在稳定版 Rust 中使用未稳定配置项的方法、配置示例及其他全局配置项说明，请参阅：[Rustfmt 配置相关说明](./../Appendix/tools/rustfmt.md) 。
 
 
 ## 列表
 
-- [P.FMT.01 始终使用 rustfmt 进行自动格式化代码](./fmt/P.FMT.01.md)
-- [P.FMT.02 缩进始终使用空格（space）而非制表符（tab）](./fmt/P.FMT.02.md)
+- [P.FMT.01 使用 rustfmt 进行自动格式化代码](./fmt/P.FMT.01.md)
+- [P.FMT.02 缩进使用空格（space）而非制表符（tab）](./fmt/P.FMT.02.md)
 - [P.FMT.03 行间距最大宽度空一行](./fmt/P.FMT.03.md)
-- [P.FMT.04 语言项（Item) 定义时花括号（brace）位置应该与语言项保持同一行](./fmt/P.FMT.04.md)
+- [P.FMT.04 语言项（Item) 定义时左花括号（brace）位置应该与语言项保持同一行](./fmt/P.FMT.04.md)
 - [P.FMT.05 存在多个标识符时应该保持块状（Block）缩进](./fmt/P.FMT.05.md)
-- [P.FMT.06 当有多行表达式操作时，操作符应该置于行首](./fmt/P.FMT.09.md)
-- [P.FMT.07 枚举变体和结构体字段相互之间默认左对齐](./fmt/P.FMT.10.md)
-- [P.FMT.08 多个函数参数和导入模块的布局](./fmt/P.FMT.11.md)
-- [P.FMT.09 空格使用规则](./fmt/P.FMT.12.md)
-- [P.FMT.10 match 分支格式](./fmt/P.FMT.14.md)
-- [P.FMT.11 导入模块分组规则](./fmt/P.FMT.15.md)
-- [P.FMT.12 声明宏分支格式](./fmt/P.FMT.16.md)
-- [P.FMT.13 具名结构体字段初始化时字段名最好不要省略](./fmt/P.FMT.17.md)
-- [P.FMT.14 extern 外部函数需要显式指定 ABI](./fmt/P.FMT.18.md)
-- [P.FMT.15 解构元组的时候允许使用`..`来指代剩余元素](./fmt/P.FMT.19.md)
-- [P.FMT.16 不要将多个不相关的派生(Derive)宏合并为同一行](./fmt/P.FMT.20.md)
+- [P.FMT.06 当有多行表达式操作时，操作符应该置于行首](./fmt/P.FMT.06.md)
+- [P.FMT.07 枚举变体和结构体字段都应左对齐](./fmt/P.FMT.07.md)
+- [P.FMT.08 函数参数超过五个或导入模块个数超过四个需换行](./fmt/P.FMT.08.md)
+- [P.FMT.09 不同的场景，使用不同的空格风格](./fmt/P.FMT.09.md)
+- [P.FMT.10  `match` 分支应该具有良好的可读性](./fmt/P.FMT.10.md)
+- [P.FMT.11 导入模块分组应该具有良好的可读性](./fmt/P.FMT.11.md)
+- [P.FMT.12 声明宏分支应该具有良好的可读性](./fmt/P.FMT.12.md)
+- [P.FMT.13 具名结构体字段初始化时不要省略字段名](./fmt/P.FMT.13.md)
+- [P.FMT.14 extern 外部函数需要显式指定 ABI](./fmt/P.FMT.14.md)
+- [P.FMT.15 解构元组的时候允许使用`..`来指代剩余元素](./fmt/P.FMT.15.md)
+- [P.FMT.16 不要将多个不相关的派生(Derive)宏合并为同一行](./fmt/P.FMT.16.md)

src/safe-guides/code_style/fmt/P.FMT.01.md

@@ -1,8 +1,8 @@
-## P.FMT.01  始终使用 rustfmt 进行自动格式化代码
+## P.FMT.01  使用 rustfmt 进行自动格式化代码
 
 **【描述】**
 
-应该总是在项目中添加 `rustfmt.toml` 或 `.rustfmt.toml`文件，即使它是空文件。这是向潜在的合作者表明你希望代码是自动格式化的。
+应该总是在项目中添加 `rustfmt.toml` 或 `.rustfmt.toml`文件。即使它是空文件，这是向潜在的合作者表明你希望代码是自动格式化的。
 
 **【例外】**
 
@@ -72,12 +72,3 @@ fn main() {
 }
 ```
 
-**【Lint 检测】**
-
-| lint name | Clippy 可检测 | Rustc 可检测 | Lint Group |是否可定制|
-| ------ | ---- | --------- | ------ | ------ |
-|  _ | no | no | _ | yes |
-
-【定制化建议】
-
-通过检测 项目 根目录下是否存在 `rustfmt.toml` 或 `.rustfmt.toml` ，如果没有该文件，则发出警告，让开发者使用 rustfmt 来格式化代码。

src/safe-guides/code_style/fmt/P.FMT.02.md

@@ -1,17 +1,11 @@
-## P.FMT.02  缩进始终使用空格（space）而非制表符（tab）
-
+## P.FMT.02  缩进使用空格（space）而非制表符（tab）
 
 **【描述】**
 
-1. 缩进要使用 四个 空格，不要使用制表符（`\t`）代替。
-2. 通过 IDE/Editor 为缩进默认好设置值。
+缩进要使用四个空格，不要使用制表符（`\t`）代替。可以通过 IDE 或编辑器把缩进设置为四个空格。
 
 **【rustfmt 配置】**
 
-此规则 Clippy 不可检测，由 rustfmt 自动格式化。
-
-rustfmt 配置：
-
 | 对应选项 | 可选值 | 是否 stable | 说明|
 | ------ | ---- | ---- | ---- | 
 | [`tab_spaces`](https://rust-lang.github.io/rustfmt/#tab_spaces) | 4| yes（默认）| 缩进空格数｜

src/safe-guides/code_style/fmt/P.FMT.03.md

@@ -10,12 +10,12 @@
 fn foo() {
     println!("a");
 }
-// 1
-// 2
+// 不符合：空两行 
+// 不符合：空两行
 fn bar() {
     println!("b");
-// 1
-// 2
+// 不符合：空两行 
+// 不符合：空两行
     println!("c");
 }
 ```
@@ -26,7 +26,7 @@ fn bar() {
 fn foo() {
     println!("a");
 }
-// 1
+// 符合：空一行 
 fn bar() {
     println!("b");
     println!("c");
@@ -41,18 +41,14 @@ fn foo() {
 }
 fn bar() {
     println!("b");
-	// 1
+	// 符合：空一行 
     println!("c");
 }
 
 ```
 
 **【rustfmt 配置】**
 
-此规则 Clippy 不可检测，由 rustfmt 自动格式化。
-
-rustfmt 配置：
-
 | 对应选项 | 可选值 | 是否 stable | 说明 |
 | ------ | ---- | ---- | ---- | 
 | [`blank_lines_lower_bound`](https://rust-lang.github.io/rustfmt/?#blank_lines_lower_bound) | 0（默认） | No| 不空行|

src/safe-guides/code_style/fmt/P.FMT.04.md

@@ -1,43 +1,35 @@
-## P.FMT.04  语言项（Item) 定义时花括号（brace）位置应该与语言项保持同一行
+## P.FMT.04  语言项（Item) 定义时左花括号（brace）位置应该与语言项保持同一行
 
 **【描述】**
 
-花括号的位置风格默认使用 `SameLineWhere`，但是也根据不同的语言项略有区别。
+为了保持代码结构的良好可读性，Rust 中定义各种语言项，包括控制结构（`if / match` 等）、函数、结构体、枚举等，要求左花括号与其定义保持同一行。
+
+但是如果携带 `where`语句，则要求换行，并且`where` 子句和 `where` 关键字不在同一行。
+
+`rustfmt` 提供三个配置项对不同的语言项进行格式化：
+
+- `brace_style` 配置项对应于大部分语言项，包括函数、结构体等，但是控制结构（`if / match`等）除外，默认值为`SameLineWhere`，代表左花括号与语言项定义保持同一行。
+- `where_single_line` 配置项对应于 `where` 语句，默认值是 `false`，表示 `where`语句的花括号是换行。
+- `control_brace_style` 配置项对应于控制结构（`if / match`等），默认值为`AlwaysSameLine`，表示左花括号与语言项定义保持同一行。
+
+所以，只需要使用 `rustfmt` 默认配置即可。
 
 **【反例】**
 
-如果设置 `brace_style = "AlwaysNextLine"`，则：
+如果设置 `brace_style = "AlwaysNextLine"`，则不符合。
 
 ```rust
+// 不符合： 左花括号与函数语言项定义未保持同一行
 fn lorem()
 {
     // body
 }
-
-fn lorem(ipsum: usize)
-{
-    // body
-}
-
-fn lorem<T>(ipsum: T)
-where
-    T: Add + Sub + Mul + Div,
-{
-    // body
-}
 ```
 
-如果设置 `brace_style = "PreferSameLine"`，则：
+如果设置 `brace_style = "PreferSameLine"`，则符合：
 
 ```rust
-fn lorem() {
-    // body
-}
-
-fn lorem(ipsum: usize) {
-    // body
-}
-
+// 不符合： 左花括号与 where 语句 应该换行
 fn lorem<T>(ipsum: T)
 where
     T: Add + Sub + Mul + Div, { // 注意这里和 `SameLineWhere`的区别
@@ -48,30 +40,21 @@ where
 结构体与枚举：
 
 
-如果设置 `brace_style = "AlwaysNextLine"`，则：
+如果设置 `brace_style = "AlwaysNextLine"`，则不符合：
 
 
 ```rust
+// 不符合： 左花括号与结构体语言项定义未保持同一行
 struct Lorem
 {
     ipsum: bool,
 }
-
-struct Dolor<T>
-where
-    T: Eq,
-{
-    sit: T,
-}
 ```
 
-如果设置 `brace_style = "PreferSameLine"`，则：
+如果设置 `brace_style = "PreferSameLine"`，则符合：
 
 ```rust
-struct Lorem {
-    ipsum: bool,
-}
-
+// 不符合： 左花括号与 where 语句应该换行
 struct Dolor<T>
 where
     T: Eq, {
@@ -81,10 +64,11 @@ where
 
 流程控制倾向于默认使用 `AlwaysSameLine`，即，总在同一行。因为流程控制没有`where`子句。
 
-如果设置 `brace_style = "AlwaysNextLine"`，则：
+如果设置 `brace_style = "AlwaysNextLine"`，则不符合：
 
 ```rust
 fn main() {
+    // 不符合： 左花括号与控制结构未保持同一行
     if lorem
     {
         println!("ipsum!");
@@ -96,64 +80,36 @@ fn main() {
 }
 ```
 
-如果设置 `brace_style = "ClosingNextLine"`，则：
-
-```rust
-fn main() {
-    if lorem {
-        println!("ipsum!");
-    } // 注意这里 if 分支结尾处，else 换行
-    else { 
-        println!("dolor!");
-    }
-}
-```
-
 
 **【正例】**
 
 函数：
 
 ```rust
-fn lorem() { // 花括号和fn定义在同一行
+// 符合： 左花括号和 函数语言项定义在同一行
+fn lorem() { 
     // body
 }
 
-fn lorem(ipsum: usize) { // 花括号和fn定义在同一行
-    // body
-}
-
-// 当有 `where` 子句的时候，花括号换行
-// 并且，`where` 子句和 `where` 关键字不在同一行
 fn lorem<T>(ipsum: T)
-where
+where // 符合：`where` 子句和 `where` 关键字不在同一行
     T: Add + Sub + Mul + Div,
-{
-    // body
-}
-```
-
-通过配置 `where_single_line` 为 true，方可设置 `where`子句在同一行，如下：
-
-```rust
-// 当有 `where` 子句的时候，花括号换行
-// 设置了 `where_single_line=true` ，则`where` 子句和 `where` 关键字在同一行
-fn lorem<T>(ipsum: T)
-where T: Add + Sub + Mul + Div,
-{
+{ // 符合：当有 `where` 子句的时候，花括号换行
     // body
 }
 ```
 
  结构体与枚举
 
 ```rust
+// 符合
 struct Lorem {
     ipsum: bool,
 }
 
+// 符合
 struct Dolor<T>
-where
+where 
     T: Eq,
 {
     sit: T,
@@ -163,6 +119,7 @@ where
 流程控制倾向于默认使用 `AlwaysSameLine`，即，总在同一行。因为流程控制没有`where`子句。
 
 ```rust
+// 符合
 // "AlwaysSameLine" (default)
 fn main() {
     if lorem {
@@ -175,15 +132,11 @@ fn main() {
 
 **【rustfmt 配置】**
 
-此规则 Clippy 不可检测，由 rustfmt 自动格式化。
-
-rustfmt 配置：
-
 | 对应选项 | 可选值 | 是否 stable | 说明 |
 | ------ | ---- | ---- | ---- | 
 | [`brace_style`](https://rust-lang.github.io/rustfmt/?#brace_style) | SameLineWhere （默认）| No| 应该与语言项保持同一行，但是 where 语句例外 |
 |[`brace_style`](https://rust-lang.github.io/rustfmt/?#brace_style)| AlwaysNextLine | No | 应该在语言项的下一行 |
 |[`brace_style`](https://rust-lang.github.io/rustfmt/?#brace_style)| PreferSameLine | No | 总是优先与语言项保持同一行，where 语句也不例外 |
 |[`where_single_line`](https://rust-lang.github.io/rustfmt/?#where_single_line)| false（默认）| No |  强制将 `where` 子句放在同一行上 |
-|[`brace_style` in control-flow](https://rust-lang.github.io/rustfmt/?#AlwaysSameLine)| AlwaysSameLine （默认） | No |  总在同一行上，用于控制流程中默认值 |
-|[`brace_style` in control-flow](https://rust-lang.github.io/rustfmt/?#ClosingNextLine)| ClosingNextLine| No |  用于控制流程中 else 分支在 if 分支结尾处换行|
+|[`control_brace_style` in control-flow](https://rust-lang.github.io/rustfmt/?#control_brace_style)| AlwaysSameLine （默认） | No |  总在同一行上，用于控制流程中默认值 |
+|[`control_brace_style` in control-flow](https://rust-lang.github.io/rustfmt/?#control_brace_style)| ClosingNextLine| No |  用于控制流程中 else 分支在 if 分支结尾处换行|