Rust-Coding-Guidelines · ZhangHanDong · Apr 23, 2025 · Dec 21, 2024
diff --git a/src/safe-guides/code_style/comments/G.CMT.01.md b/src/safe-guides/code_style/comments/G.CMT.01.md
@@ -40,6 +40,6 @@ pub fn read(filename: String) -> io::Result<String> {
 
 **【Lint 检测】**
 
-| lint name | Clippy 可检测 | Rustc 可检测 | Lint Group | 默认 level |
-| ------ | ---- | --------- | ------ | ------ | 
-| [missing_errors_doc ](https://rust-lang.github.io/rust-clippy/master/index.html#missing_errors_doc ) | yes| no | Style | allow | 
+| lint name                                                                                          | Clippy 可检测 | Rustc 可检测 | Lint Group | 默认 level |
+| -------------------------------------------------------------------------------------------------- | ------------- | ------------ | ---------- | ---------- |
+| [missing_errors_doc](https://rust-lang.github.io/rust-clippy/master/index.html#missing_errors_doc) | yes           | no           | Style      | allow      |
diff --git a/src/safe-guides/code_style/comments/G.CMT.02.md b/src/safe-guides/code_style/comments/G.CMT.02.md
@@ -43,8 +43,8 @@ pub fn divide_by(x: i32, y: i32) -> i32 {
 
 **【Lint 检测】**
 
-| lint name | Clippy 可检测 | Rustc 可检测 | Lint Group | 默认 level |
-| ------ | ---- | --------- | ------ | ------ | 
-| [missing_panics_doc ](https://rust-lang.github.io/rust-clippy/master/index.html#missing_panics_doc ) | yes| no | Style | allow | 
+| lint name                                                                                          | Clippy 可检测 | Rustc 可检测 | Lint Group | 默认 level |
+| -------------------------------------------------------------------------------------------------- | ------------- | ------------ | ---------- | ---------- |
+| [missing_panics_doc](https://rust-lang.github.io/rust-clippy/master/index.html#missing_panics_doc) | yes           | no           | Style      | allow      |
 
 默认为 `allow`，但是此规则需要设置`#![warn(clippy::missing_panics_doc)]`。
diff --git a/src/safe-guides/code_style/comments/G.CMT.03.md b/src/safe-guides/code_style/comments/G.CMT.03.md
@@ -50,6 +50,6 @@ pub struct DoubleString {
 
 **【Lint 检测】**
 
-| lint name                                                    | Clippy 可检测 | Rustc 可检测 | Lint Group | 默认 level |
-| ------------------------------------------------------------ | ------------- | ------------ | ---------- | ---------- |
-| [tabs_in_doc_comments ](https://rust-lang.github.io/rust-clippy/master/index.html#tabs_in_doc_comments ) | yes           | no           | Style      | warn       |
+| lint name                                                                                              | Clippy 可检测 | Rustc 可检测 | Lint Group | 默认 level |
+| ------------------------------------------------------------------------------------------------------ | ------------- | ------------ | ---------- | ---------- |
+| [tabs_in_doc_comments](https://rust-lang.github.io/rust-clippy/master/index.html#tabs_in_doc_comments) | yes           | no           | Style      | warn       |
diff --git a/src/safe-guides/code_style/comments/P.CMT.01.md b/src/safe-guides/code_style/comments/P.CMT.01.md
@@ -13,7 +13,7 @@
 1. 文档注释中内容用语应该尽量简短精干，不宜篇幅过长。请确保你的代码注释良好并且易于他人理解，好的注释能够传达上下文关系和代码目的。
 2. 注释内容始终围绕两个关键点来构建：
     - What : 用于阐述代码为了什么而实现。
-    - how : 用于阐述代码如何去使用。
+    - How : 用于阐述代码如何去使用。
 3. 注释和文档注释使用的自然语言要保持一致。
 4. Rust 项目文档应该始终基于 `rustdoc` 工具来构建，`rustdoc` 支持 Markdown 格式，为了使得文档更加美观易读，文档注释应该使用 Markdown 格式。
 

diff --git a/src/safe-guides/code_style/comments/P.CMT.04.md b/src/safe-guides/code_style/comments/P.CMT.04.md
@@ -18,7 +18,7 @@
 - 中文版：`版权所有（c）XXX 技术有限公司 2015-2022`。
 - 英文版： `Copyright (c) XXX Technologies Co.Ltd. 2015-2022. All rights reserved. Licensed under Apache-2.0.`
 
-其内容可以进行调整，参加下面详细说明：
+其内容可以进行调整，参见下面详细说明：
 
 - `2015-2022` 根据实际需要可以修改。2015是文件首次创建年份，2022是文件最后修改年份。可以只写一个创建年份，后续如果经常修改则无需修改版权声明。
 - 如果是内部使用，则无需增加 `All rights reserved`。

diff --git a/src/safe-guides/code_style/fmt/P.FMT.04.md b/src/safe-guides/code_style/fmt/P.FMT.04.md
@@ -1,4 +1,4 @@
-## P.FMT.04  语言项（Item) 定义时左花括号（brace）位置应该与语言项保持同一行
+## P.FMT.04  语言项（Item）定义时左花括号（brace）位置应该与语言项保持同一行
 
 **【描述】**
 
@@ -99,7 +99,7 @@ where // 符合：`where` 子句和 `where` 关键字不在同一行
 }
 ```
 
- 结构体与枚举
+ 结构体与枚举：
 
 ```rust
 // 符合
@@ -132,11 +132,11 @@ fn main() {
 
 **【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` 子句放在同一行上 |
-|[`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 分支结尾处换行|
+| 对应选项                                                                                           | 可选值                  | 是否 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` 子句放在同一行上                |
+| [`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 分支结尾处换行   |
diff --git a/src/safe-guides/code_style/fmt/P.FMT.05.md b/src/safe-guides/code_style/fmt/P.FMT.05.md
@@ -19,7 +19,7 @@ fn main() {
 }
 ```
 
-流程控制
+流程控制：
 
 ```rust
 fn main() {
@@ -37,7 +37,7 @@ fn main() {
 }
 ```
 
-函数参数
+函数参数：
 
 
 ```rust
@@ -56,7 +56,7 @@ fn lorem(ipsum: usize,
 }
 ```
 
-函数调用
+函数调用：
 
 ```rust
 fn main() {
@@ -72,7 +72,7 @@ fn main() {
 }
 ```
 
-泛型
+泛型：
 
 
 ```rust
@@ -96,7 +96,7 @@ fn lorem<Ipsum: Eq = usize,
 }
 ```
 
-结构体
+结构体：
 
 ```rust
 fn main() {
@@ -125,7 +125,7 @@ fn main() {
 }
 ```
 
-流程控制
+流程控制：
 
 ```rust
 fn main() {
@@ -143,7 +143,7 @@ fn main() {
 }
 ```
 
-函数参数
+函数参数：
 
 ```rust
 fn lorem() {}
@@ -165,7 +165,7 @@ fn lorem(
 
 ```
 
-函数调用
+函数调用：
 
 ```rust
 fn main() {
@@ -183,7 +183,7 @@ fn main() {
 }
 ```
 
-泛型
+泛型：
 
 ```rust
 // 符合： 缩进四个空格
@@ -208,7 +208,7 @@ fn lorem<
 }
 ```
 
-结构体
+结构体：
 
 ```rust
 fn main() {
@@ -221,7 +221,7 @@ fn main() {
 
 **【rustfmt 配置】**
 
-| 对应选项 | 可选值 | 是否 stable | 说明 |
-| ------ | ---- | ---- | ---- | 
-| [`indent_style`](https://rust-lang.github.io/rustfmt/?#indent_style) | Block（默认） | No| 多个标识符定义保持块状风格，缩进符合标准 |
-| [`indent_style`](https://rust-lang.github.io/rustfmt/?#indent_style) | Visual | No| 多个标识符定义保持对齐风格，但不符合缩进标准 |
+| 对应选项                                                             | 可选值        | 是否 stable | 说明                                         |
+| -------------------------------------------------------------------- | ------------- | ----------- | -------------------------------------------- |
+| [`indent_style`](https://rust-lang.github.io/rustfmt/?#indent_style) | Block（默认） | No          | 多个标识符定义保持块状风格，缩进符合标准     |
+| [`indent_style`](https://rust-lang.github.io/rustfmt/?#indent_style) | Visual        | No          | 多个标识符定义保持对齐风格，但不符合缩进标准 |
diff --git a/src/safe-guides/code_style/fmt/P.FMT.06.md b/src/safe-guides/code_style/fmt/P.FMT.06.md
@@ -6,7 +6,7 @@
 
 **【反例】**
 
-操作符置于行尾
+操作符置于行尾：
 
 ```rust
 fn main() {
@@ -25,7 +25,7 @@ fn main() {
 
 **【正例】**
 
-操作符置于行首
+操作符置于行首：
 
 ```rust
 fn main() {
@@ -45,6 +45,6 @@ fn main() {
 
 **【rustfmt 配置】**
 
-| 对应选项 | 可选值 | 是否 stable | 说明 |
-| ------ | ---- | ---- | ---- | 
-| [`binop_separator`](https://rust-lang.github.io/rustfmt/?#binop_separator) | Front（默认） | No| 换行后，操作符置于行首 |
+| 对应选项                                                                   | 可选值        | 是否 stable | 说明                   |
+| -------------------------------------------------------------------------- | ------------- | ----------- | ---------------------- |
+| [`binop_separator`](https://rust-lang.github.io/rustfmt/?#binop_separator) | Front（默认） | No          | 换行后，操作符置于行首 |
diff --git a/src/safe-guides/code_style/fmt/P.FMT.08.md b/src/safe-guides/code_style/fmt/P.FMT.08.md
@@ -49,7 +49,6 @@ use foo::{
 当 rustfmt 配置项 `fn_args_layout` 和 `imports_layout` 使用默认值时：
 
 ```rust
-
 trait Lorem {
     fn lorem(ipsum: Ipsum, dolor: Dolor, sit: Sit, amet: Amet, consectetur: Consectetur);
 
@@ -93,7 +92,7 @@ use foo::{
 
 **【rustfmt 配置】**
 
-| 对应选项 | 可选值 | 是否 stable | 说明 |
-| ------ | ---- | ---- | ---- | 
-| [`fn_args_layout`](https://rust-lang.github.io/rustfmt/?#fn_args_layout) | Tall（默认） | Yes|  函数参数五个或以内可以一行，超过五个则使用块状缩进|
-| [`imports_layout`](https://rust-lang.github.io/rustfmt/?#imports_layout) | Mixed（默认） | No| 导入模块每行超过四个则换行 |
+| 对应选项                                                                 | 可选值        | 是否 stable | 说明                                               |
+| ------------------------------------------------------------------------ | ------------- | ----------- | -------------------------------------------------- |
+| [`fn_args_layout`](https://rust-lang.github.io/rustfmt/?#fn_args_layout) | Tall（默认）  | Yes         | 函数参数五个或以内可以一行，超过五个则使用块状缩进 |
+| [`imports_layout`](https://rust-lang.github.io/rustfmt/?#imports_layout) | Mixed（默认） | No          | 导入模块每行超过四个则换行                         |
diff --git a/src/safe-guides/code_style/fmt/P.FMT.12.md b/src/safe-guides/code_style/fmt/P.FMT.12.md
@@ -51,7 +51,7 @@ macro_rules! foo {
 
 **【rustfmt 配置】**
 
-| 对应选项 | 可选值 | 是否 stable | 说明 |
-| ------ | ---- | ---- | ---- | 
-| [`format_macro_matchers`](https://rust-lang.github.io/rustfmt/?#format_macro_matchers) | （false（默认），true(建议)） | No |声明宏 模式匹配分支（`=>` 左侧）中要使用紧凑格式|
-| [`format_macro_bodies`](https://rust-lang.github.io/rustfmt/?#format_macro_bodies) | true（默认） | No| 声明宏分支代码体（`=>` 右侧） 使用宽松格式|
+| 对应选项                                                                               | 可选值                      | 是否 stable | 说明                                             |
+| -------------------------------------------------------------------------------------- | --------------------------- | ----------- | ------------------------------------------------ |
+| [`format_macro_matchers`](https://rust-lang.github.io/rustfmt/?#format_macro_matchers) | false（默认），true（建议） | No          | 声明宏 模式匹配分支（`=>` 左侧）中要使用紧凑格式 |
+| [`format_macro_bodies`](https://rust-lang.github.io/rustfmt/?#format_macro_bodies)     | true（默认）                | No          | 声明宏分支代码体（`=>` 右侧） 使用宽松格式       |
diff --git a/src/safe-guides/code_style/naming/G.NAM.01.md b/src/safe-guides/code_style/naming/G.NAM.01.md
@@ -5,28 +5,28 @@
 
 **【描述】**
 
-Rust 倾向于在“类型”级的结构中使用驼峰（ `UpperCamelCase`） 命名风格，在 “变量、值（实例）、函数名”等结构中使用蛇形（ `snake_case`）命名风格。
+Rust 倾向于在“类型”级的结构中使用大驼峰（`UpperCamelCase`） 命名风格，在 “变量、值（实例）、函数名”等结构中使用蛇形（`snake_case`）命名风格。
 
 下面是汇总信息：
 
-| Item | 规范 |
-| ---- | ---------- |
-| 包（Crates） | [通常使用 snake_case](https://github.com/rust-lang/api-guidelines/issues/29) [^crate-name] |
-| 模块（Modules） | `snake_case` |
-| 类型（Types） | `UpperCamelCase` |
-| 特质（Traits） | `UpperCamelCase` |
-| 枚举体（Enum variants） | `UpperCamelCase` |
-| 函数（Functions） | `snake_case` |
-| 方法（Methods） | `snake_case` |
-| 通用构造函数（General constructors） | `new` 或者 `with_more_details` |
-| 转换构造函数（Conversion constructors） | `from_some_other_type` |
-| 宏（Macros） | `snake_case!` |
-| 本地变量（Local variables） | `snake_case` |
-| 静态变量（Statics） | `SCREAMING_SNAKE_CASE` |
-| 常量（Constants） | `SCREAMING_SNAKE_CASE` |
-| 类型参数（Type parameters） | 简明的 `UpperCamelCase` ，通常使用单个大写字母： `T` |
-| 生存期（Lifetimes） | 简短的 `lowercase`，通常使用单个小写字母 `'a`, `'de`, `'src`，尽量保持语义 |
-| 特性（Features） | `snake_case` |
+| Item                                    | 规范                                                                                       |
+| --------------------------------------- | ------------------------------------------------------------------------------------------ |
+| 包（Crates）                            | [通常使用 snake_case](https://github.com/rust-lang/api-guidelines/issues/29) [^crate-name] |
+| 模块（Modules）                         | `snake_case`                                                                               |
+| 类型（Types）                           | `UpperCamelCase`                                                                           |
+| 特质（Traits）                          | `UpperCamelCase`                                                                           |
+| 枚举体（Enum variants）                 | `UpperCamelCase`                                                                           |
+| 函数（Functions）                       | `snake_case`                                                                               |
+| 方法（Methods）                         | `snake_case`                                                                               |
+| 通用构造函数（General constructors）    | `new` 或者 `with_more_details`                                                             |
+| 转换构造函数（Conversion constructors） | `from_some_other_type`                                                                     |
+| 宏（Macros）                            | `snake_case!`                                                                              |
+| 本地变量（Local variables）             | `snake_case`                                                                               |
+| 静态变量（Statics）                     | `SCREAMING_SNAKE_CASE`                                                                     |
+| 常量（Constants）                       | `SCREAMING_SNAKE_CASE`                                                                     |
+| 类型参数（Type parameters）             | 简明的 `UpperCamelCase` ，通常使用单个大写字母： `T`                                       |
+| 生命周期（Lifetimes）                   | 简短的 `lowercase`，通常使用单个小写字母 `'a`, `'de`, `'src`，尽量保持语义                 |
+| 特性（Features）                        | `snake_case`                                                                               |
 
 说明 :
 
@@ -46,7 +46,7 @@ Rust 命名规范在 [RFC 0430](https://github.com/rust-lang/rfcs/blob/master/te
 
 **【Lint 检测】**
 
-| lint name | Clippy 可检测 | Rustc 可检测 | Lint Group |
-| ------ | ---- | --------- | ------ |
-| [`Rustc: non_camel_case_types`](https://doc.rust-lang.org/rustc/lints/listing/warn-by-default.html#non-camel-case-types) | no | yes | Style |
-| [`Rustc: non_snake_case`](https://doc.rust-lang.org/rustc/lints/listing/warn-by-default.html#non-snake-case) | no | yes | Style |
+| lint name                                                                                                                | Clippy 可检测 | Rustc 可检测 | Lint Group |
+| ------------------------------------------------------------------------------------------------------------------------ | ------------- | ------------ | ---------- |
+| [`Rustc: non_camel_case_types`](https://doc.rust-lang.org/rustc/lints/listing/warn-by-default.html#non-camel-case-types) | no            | yes          | Style      |
+| [`Rustc: non_snake_case`](https://doc.rust-lang.org/rustc/lints/listing/warn-by-default.html#non-snake-case)             | no            | yes          | Style      |