├── .gitignore ├── src ├── safe-guides │ ├── Appendix │ │ ├── test.md │ │ ├── toc.md │ │ ├── dev_env.md │ │ ├── terms.md │ │ ├── test │ │ │ ├── fuzz.md │ │ │ ├── benchmark.md │ │ │ └── unit_test.md │ │ ├── contribution.md │ │ ├── rustc-flag.md │ │ ├── tools │ │ │ ├── intro.md │ │ │ ├── rustfmt.md │ │ │ ├── cargo-udeps.md │ │ │ └── noisy-clippy.md │ │ ├── optimizing │ │ │ └── intro.md │ │ ├── templates │ │ │ ├── intro.md │ │ │ ├── deny.toml.md │ │ │ ├── clippy.toml.md │ │ │ └── rustfmt.toml.md │ │ ├── best-practice │ │ │ ├── intro.md │ │ │ ├── qa.md │ │ │ └── tips.md │ │ └── cheat-sheet │ │ │ ├── Numbers │ │ │ └── float.md │ │ │ └── README.md │ ├── code_style.md │ ├── coding_practice.md │ ├── coding_practice │ │ ├── io.md │ │ ├── consts.md │ │ ├── expr.md │ │ ├── generic.md │ │ ├── macros.md │ │ ├── memory.md │ │ ├── module.md │ │ ├── others.md │ │ ├── statics.md │ │ ├── strings.md │ │ ├── threads.md │ │ ├── traits.md │ │ ├── collections.md │ │ ├── control-flow.md │ │ ├── data-type.md │ │ ├── data-type │ │ │ ├── bool.md │ │ │ ├── char.md │ │ │ ├── int.md │ │ │ ├── array.md │ │ │ ├── enum.md │ │ │ ├── float.md │ │ │ ├── slice.md │ │ │ ├── struct.md │ │ │ ├── tuple.md │ │ │ ├── vec.md │ │ │ ├── G.TYP.02.md │ │ │ ├── G.TYP.01.md │ │ │ ├── bool │ │ │ │ ├── G.TYP.BOL.06.md │ │ │ │ ├── G.TYP.BOL.01.md │ │ │ │ ├── G.TYP.BOL.03.md │ │ │ │ ├── G.TYP.BOL.04.md │ │ │ │ ├── G.TYP.BOL.02.md │ │ │ │ └── G.TYP.BOL.05.md │ │ │ ├── enum │ │ │ │ ├── G.TYP.ENM.02.md │ │ │ │ ├── G.TYP.ENM.06.md │ │ │ │ ├── G.TYP.ENM.01.md │ │ │ │ ├── G.TYP.ENM.04.md │ │ │ │ ├── G.TYP.ENM.05.md │ │ │ │ └── G.TYP.ENM.03.md │ │ │ ├── vec │ │ │ │ ├── G.TYP.VEC.01.md │ │ │ │ ├── P.TYP.VEC.01.md │ │ │ │ └── P.TYP.VEC.02.md │ │ │ ├── array │ │ │ │ ├── G.TYP.ARR.02.md │ │ │ │ ├── G.TYP.ARR.01.md │ │ │ │ └── G.TYP.ARR.03.md │ │ │ ├── char │ │ │ │ ├── G.TYP.CHR.01.md │ │ │ │ ├── G.TYP.CHR.02.md │ │ │ │ └── G.TYP.CHR.03.md │ │ │ ├── int │ │ │ │ ├── G.TYP.INT.03.md │ │ │ │ ├── G.TYP.INT.02.md │ │ │ │ └── G.TYP.INT.01.md │ │ │ ├── slice │ │ │ │ ├── P.TYP.SLC.01.md │ │ │ │ └── P.TYP.SLC.02.md │ │ │ ├── tuple │ │ │ │ └── G.TYP.TUP.01.md │ │ │ ├── P.TYP.01.md │ │ │ ├── float │ │ │ │ ├── G.TYP.FLT.04.md │ │ │ │ ├── G.TYP.FLT.02.md │ │ │ │ ├── G.TYP.FLT.01.md │ │ │ │ ├── G.TYP.FLT.05.md │ │ │ │ └── G.TYP.FLT.03.md │ │ │ ├── G.TYP.03.md │ │ │ └── struct │ │ │ │ ├── G.TYP.SCT.03.md │ │ │ │ ├── G.TYP.SCT.02.md │ │ │ │ ├── P.TYP.SCT.01.md │ │ │ │ ├── P.TYP.SCT.02.md │ │ │ │ └── G.TYP.SCT.01.md │ │ ├── error-handle.md │ │ ├── macros │ │ │ ├── decl.md │ │ │ ├── proc.md │ │ │ ├── P.MAC.01.md │ │ │ ├── G.MAC.01.md │ │ │ ├── G.MAC.02.md │ │ │ ├── proc │ │ │ │ ├── P.MAC.PRO.03.md │ │ │ │ ├── P.MAC.PRO.04.md │ │ │ │ ├── P.MAC.PRO.01.md │ │ │ │ ├── P.MAC.PRO.02.md │ │ │ │ ├── P.MAC.PRO.06.md │ │ │ │ └── P.MAC.PRO.05.md │ │ │ ├── P.MAC.02.md │ │ │ └── decl │ │ │ │ ├── P.MAC.DCL.04.md │ │ │ │ ├── P.MAC.DCL.07.md │ │ │ │ ├── P.MAC.DCL.01.md │ │ │ │ ├── P.MAC.DCL.03.md │ │ │ │ ├── P.MAC.DCL.06.md │ │ │ │ ├── P.MAC.DCL.02.md │ │ │ │ ├── P.MAC.DCL.08.md │ │ │ │ └── P.MAC.DCL.05.md │ │ ├── memory │ │ │ ├── box.md │ │ │ ├── drop.md │ │ │ ├── lifetime.md │ │ │ ├── smart-ptr.md │ │ │ ├── drop │ │ │ │ └── G.MEM.DRP.01.md │ │ │ ├── box │ │ │ │ ├── G.MEM.BOX.01.md │ │ │ │ ├── G.MEM.BOX.03.md │ │ │ │ └── G.MEM.BOX.02.md │ │ │ ├── lifetime │ │ │ │ ├── P.MEM.LFT.01.md │ │ │ │ └── P.MEM.LFT.02.md │ │ │ └── smart-ptr │ │ │ │ └── P.MEM.SPT.01.md │ │ ├── no-std.md │ │ ├── security.md │ │ ├── threads │ │ │ ├── lock.md │ │ │ ├── lock-free.md │ │ │ ├── lock-free │ │ │ │ ├── P.MTH.LKF.01.md │ │ │ │ └── P.MTH.LKF.02.md │ │ │ └── lock │ │ │ │ ├── G.MTH.LCK.01.md │ │ │ │ ├── P.MTH.LCK.01.md │ │ │ │ ├── G.MTH.LCK.02.md │ │ │ │ ├── G.MTH.LCK.03.md │ │ │ │ └── G.MTH.LCK.04.md │ │ ├── async-await.md │ │ ├── unsafe_rust │ │ │ ├── ffi.md │ │ │ ├── io.md │ │ │ ├── mem.md │ │ │ ├── union.md │ │ │ ├── raw_ptr.md │ │ │ ├── safe_abstract.md │ │ │ ├── glossary.md │ │ │ ├── G.UNS.01.md │ │ │ ├── P.UNS.02.md │ │ │ ├── ffi │ │ │ │ ├── P.UNS.FFI.08.md │ │ │ │ ├── P.UNS.FFI.07.md │ │ │ │ ├── P.UNS.FFI.13.md │ │ │ │ ├── P.UNS.FFI.14.md │ │ │ │ ├── P.UNS.FFI.15.md │ │ │ │ ├── P.UNS.FFI.01.md │ │ │ │ ├── P.UNS.FFI.04.md │ │ │ │ ├── P.UNS.FFI.02.md │ │ │ │ ├── P.UNS.FFI.10.md │ │ │ │ ├── P.UNS.FFI.09.md │ │ │ │ ├── P.UNS.FFI.05.md │ │ │ │ ├── P.UNS.FFI.06.md │ │ │ │ ├── P.UNS.FFI.11.md │ │ │ │ ├── P.UNS.FFI.12.md │ │ │ │ └── P.UNS.FFI.03.md │ │ │ ├── P.UNS.01.md │ │ │ ├── mem │ │ │ │ ├── P.UNS.MEM.02.md │ │ │ │ ├── P.UNS.MEM.05.md │ │ │ │ ├── P.UNS.MEM.01.md │ │ │ │ ├── G.UNS.MEM.01.md │ │ │ │ ├── P.UNS.MEM.04.md │ │ │ │ └── P.UNS.MEM.03.md │ │ │ ├── raw_ptr │ │ │ │ ├── P.UNS.PTR.01.md │ │ │ │ ├── G.UNS.PTR.02.md │ │ │ │ ├── P.UNS.PTR.02.md │ │ │ │ ├── G.UNS.PTR.01.md │ │ │ │ ├── G.UNS.PTR.03.md │ │ │ │ └── P.UNS.PTR.03.md │ │ │ ├── io │ │ │ │ └── P.UNS.FIO.01.md │ │ │ ├── union │ │ │ │ ├── P.UNS.UNI.01.md │ │ │ │ └── P.UNS.UNI.02.md │ │ │ └── safe_abstract │ │ │ │ ├── P.UNS.SAS.06.md │ │ │ │ ├── P.UNS.SAS.03.md │ │ │ │ ├── P.UNS.SAS.04.md │ │ │ │ ├── P.UNS.SAS.08.md │ │ │ │ ├── P.UNS.SAS.01.md │ │ │ │ ├── P.UNS.SAS.02.md │ │ │ │ ├── P.UNS.SAS.05.md │ │ │ │ ├── P.UNS.SAS.09.md │ │ │ │ ├── G.UNS.SAS.01.md │ │ │ │ ├── P.UNS.SAS.07.md │ │ │ │ └── G.UNS.SAS.02.md │ │ ├── variables.md │ │ ├── fn-design.md │ │ ├── unsafe_rust.md │ │ ├── cargo.md │ │ ├── traits │ │ │ ├── std-builtin.md │ │ │ ├── trait-object.md │ │ │ ├── P.TRA.01.md │ │ │ ├── std-builtin │ │ │ │ ├── G.TRA.BLN.02.md │ │ │ │ ├── G.TRA.BLN.08.md │ │ │ │ ├── G.TRA.BLN.10.md │ │ │ │ ├── P.TRA.BLN.01.md │ │ │ │ ├── G.TRA.BLN.09.md │ │ │ │ ├── G.TRA.BLN.03.md │ │ │ │ ├── G.TRA.BLN.04.md │ │ │ │ ├── G.TRA.BLN.05.md │ │ │ │ ├── G.TRA.BLN.01.md │ │ │ │ ├── G.TRA.BLN.06.md │ │ │ │ └── G.TRA.BLN.07.md │ │ │ └── trait-object │ │ │ │ ├── P.TRA.OBJ.02.md │ │ │ │ └── P.TRA.OBJ.01.md │ │ ├── cargo │ │ │ ├── P.CAR.02.md │ │ │ ├── P.CAR.01.md │ │ │ ├── G.CAR.03.md │ │ │ ├── G.CAR.04.md │ │ │ ├── P.CAR.04.md │ │ │ ├── G.CAR.02.md │ │ │ ├── P.CAR.03.md │ │ │ └── G.CAR.01.md │ │ ├── consts │ │ │ ├── G.CNS.02.md │ │ │ ├── G.CNS.03.md │ │ │ ├── G.CNS.01.md │ │ │ ├── G.CNS.05.md │ │ │ └── G.CNS.04.md │ │ ├── expr │ │ │ ├── G.EXP.04.md │ │ │ ├── G.EXP.02.md │ │ │ ├── G.EXP.05.md │ │ │ ├── G.EXP.06.md │ │ │ ├── G.EXP.01.md │ │ │ └── G.EXP.03.md │ │ ├── generic │ │ │ ├── P.GEN.01.md │ │ │ ├── G.GEN.01.md │ │ │ ├── P.GEN.02.md │ │ │ ├── P.GEN.03.md │ │ │ ├── P.GEN.04.md │ │ │ ├── G.GEN.02.md │ │ │ └── P.GEN.05.md │ │ ├── async-await │ │ │ ├── G.ASY.04.md │ │ │ ├── G.ASY.05.md │ │ │ ├── G.ASY.02.md │ │ │ ├── P.ASY.01.md │ │ │ ├── G.ASY.03.md │ │ │ └── G.ASY.01.md │ │ ├── control-flow │ │ │ ├── P.CTF.01.md │ │ │ ├── P.CTF.02.md │ │ │ ├── G.CTF.02.md │ │ │ ├── G.CTF.03.md │ │ │ ├── G.CTF.04.md │ │ │ └── G.CTF.01.md │ │ ├── module │ │ │ ├── G.MOD.03.md │ │ │ ├── P.MOD.01.md │ │ │ ├── G.MOD.04.md │ │ │ ├── P.MOD.02.md │ │ │ ├── G.MOD.01.md │ │ │ ├── G.MOD.05.md │ │ │ └── G.MOD.02.md │ │ ├── variables │ │ │ ├── G.VAR.03.md │ │ │ ├── G.VAR.02.md │ │ │ ├── G.VAR.04.md │ │ │ ├── P.VAR.01.md │ │ │ ├── P.VAR.02.md │ │ │ └── G.VAR.01.md │ │ ├── strings │ │ │ ├── G.STR.02.md │ │ │ ├── P.STR.01.md │ │ │ ├── P.STR.05.md │ │ │ ├── P.STR.04.md │ │ │ ├── G.STR.01.md │ │ │ ├── G.STR.04.md │ │ │ ├── G.STR.05.md │ │ │ ├── P.STR.02.md │ │ │ ├── P.STR.03.md │ │ │ └── G.STR.03.md │ │ ├── no-std │ │ │ ├── P.EMB.01.md │ │ │ └── P.EMB.02.md │ │ ├── others │ │ │ ├── G.OTH.02.md │ │ │ └── G.OTH.01.md │ │ ├── security │ │ │ ├── P.SEC.01.md │ │ │ └── G.SEC.01.md │ │ ├── error-handle │ │ │ ├── G.ERR.02.md │ │ │ ├── P.ERR.01.md │ │ │ ├── G.ERR.01.md │ │ │ └── P.ERR.02.md │ │ ├── io │ │ │ ├── G.FIO.01.md │ │ │ └── P.FIO.01.md │ │ ├── collections │ │ │ ├── G.CLT.01.md │ │ │ └── P.CLT.01.md │ │ ├── statics │ │ │ └── G.STV.01.md │ │ └── fn-design │ │ │ ├── P.FUD.02.md │ │ │ ├── P.FUD.01.md │ │ │ ├── G.FUD.05.md │ │ │ ├── G.FUD.02.md │ │ │ ├── G.FUD.03.md │ │ │ ├── G.FUD.01.md │ │ │ ├── G.FUD.06.md │ │ │ └── G.FUD.04.md │ ├── code_style │ │ ├── fmt │ │ │ ├── P.FMT.09.md │ │ │ ├── P.FMT.12.md │ │ │ ├── P.FMT.10.md │ │ │ ├── P.FMT.11.md │ │ │ ├── P.FMT.13.md │ │ │ ├── P.FMT.15.md │ │ │ ├── P.FMT.14.md │ │ │ ├── P.FMT.16.md │ │ │ ├── P.FMT.01.md │ │ │ ├── P.FMT.02.md │ │ │ ├── P.FMT.03.md │ │ │ ├── P.FMT.07.md │ │ │ ├── P.FMT.04.md │ │ │ ├── P.FMT.05.md │ │ │ ├── P.FMT.06.md │ │ │ └── P.FMT.08.md │ │ ├── naming │ │ │ ├── G.NAM.01.md │ │ │ ├── P.NAM.03.md │ │ │ ├── P.NAM.08.md │ │ │ ├── G.NAM.02.md │ │ │ ├── P.NAM.02.md │ │ │ ├── P.NAM.06.md │ │ │ ├── P.NAM.04.md │ │ │ ├── P.NAM.09.md │ │ │ ├── P.NAM.07.md │ │ │ ├── P.NAM.01.md │ │ │ └── P.NAM.05.md │ │ ├── naming.md │ │ ├── comments.md │ │ ├── comments │ │ │ ├── P.CMT.05.md │ │ │ ├── G.CMT.01.md │ │ │ ├── G.CMT.03.md │ │ │ ├── G.CMT.02.md │ │ │ ├── P.CMT.04.md │ │ │ ├── P.CMT.03.md │ │ │ ├── P.CMT.02.md │ │ │ └── P.CMT.01.md │ │ └── fmt.md │ └── overview │ │ ├── why.md │ │ └── convention.md ├── overview.md └── SUMMARY.md ├── book.toml ├── .github └── workflows │ └── main.yml ├── LICENSE └── README.md /.gitignore: -------------------------------------------------------------------------------- 1 | book 2 | -------------------------------------------------------------------------------- /src/safe-guides/Appendix/test.md: -------------------------------------------------------------------------------- 1 | # B.测试 2 | -------------------------------------------------------------------------------- /src/safe-guides/Appendix/toc.md: -------------------------------------------------------------------------------- 1 | # 附录 2 | -------------------------------------------------------------------------------- /src/safe-guides/Appendix/dev_env.md: -------------------------------------------------------------------------------- 1 | # A.开发环境 2 | -------------------------------------------------------------------------------- /src/safe-guides/Appendix/terms.md: -------------------------------------------------------------------------------- 1 | # C.术语解释 2 | -------------------------------------------------------------------------------- /src/safe-guides/Appendix/test/fuzz.md: -------------------------------------------------------------------------------- 1 | # 模糊测试 2 | -------------------------------------------------------------------------------- /src/safe-guides/code_style.md: -------------------------------------------------------------------------------- 1 | # Coding Style 2 | -------------------------------------------------------------------------------- /src/safe-guides/coding_practice.md: -------------------------------------------------------------------------------- 1 | # 编码实践 2 | -------------------------------------------------------------------------------- /src/safe-guides/coding_practice/io.md: -------------------------------------------------------------------------------- 1 | # I/O 2 | -------------------------------------------------------------------------------- /src/safe-guides/Appendix/contribution.md: -------------------------------------------------------------------------------- 1 | # J.贡献说明 2 | -------------------------------------------------------------------------------- /src/safe-guides/Appendix/rustc-flag.md: -------------------------------------------------------------------------------- 1 | # H.编译参数说明 2 | -------------------------------------------------------------------------------- /src/safe-guides/Appendix/test/benchmark.md: -------------------------------------------------------------------------------- 1 | # 基准测试 2 | -------------------------------------------------------------------------------- /src/safe-guides/Appendix/test/unit_test.md: -------------------------------------------------------------------------------- 1 | # 单元测试 2 | -------------------------------------------------------------------------------- /src/safe-guides/Appendix/tools/intro.md: -------------------------------------------------------------------------------- 1 | # E.工具链 2 | -------------------------------------------------------------------------------- /src/safe-guides/coding_practice/consts.md: -------------------------------------------------------------------------------- 1 | # 常量 2 | -------------------------------------------------------------------------------- /src/safe-guides/coding_practice/expr.md: -------------------------------------------------------------------------------- 1 | # 表达式 2 | -------------------------------------------------------------------------------- /src/safe-guides/coding_practice/generic.md: -------------------------------------------------------------------------------- 1 | # 泛型 2 | -------------------------------------------------------------------------------- /src/safe-guides/coding_practice/macros.md: -------------------------------------------------------------------------------- 1 | # 宏 2 | -------------------------------------------------------------------------------- /src/safe-guides/coding_practice/memory.md: -------------------------------------------------------------------------------- 1 | # 内存管理 2 | -------------------------------------------------------------------------------- /src/safe-guides/coding_practice/module.md: -------------------------------------------------------------------------------- 1 | # 模块 2 | -------------------------------------------------------------------------------- /src/safe-guides/coding_practice/others.md: -------------------------------------------------------------------------------- 1 | # 其他 2 | -------------------------------------------------------------------------------- /src/safe-guides/coding_practice/statics.md: -------------------------------------------------------------------------------- 1 | # 静态变量 2 | -------------------------------------------------------------------------------- /src/safe-guides/coding_practice/strings.md: -------------------------------------------------------------------------------- 1 | # 字符串 2 | -------------------------------------------------------------------------------- /src/safe-guides/coding_practice/threads.md: -------------------------------------------------------------------------------- 1 | # 多线程 2 | -------------------------------------------------------------------------------- /src/safe-guides/coding_practice/traits.md: -------------------------------------------------------------------------------- 1 | # 特质 2 | -------------------------------------------------------------------------------- /src/safe-guides/Appendix/optimizing/intro.md: -------------------------------------------------------------------------------- 1 | # G.优化指南 2 | -------------------------------------------------------------------------------- /src/safe-guides/Appendix/templates/intro.md: -------------------------------------------------------------------------------- 1 | # D.模板 2 | -------------------------------------------------------------------------------- /src/safe-guides/Appendix/tools/rustfmt.md: -------------------------------------------------------------------------------- 1 | # rustfmt 2 | -------------------------------------------------------------------------------- /src/safe-guides/coding_practice/collections.md: -------------------------------------------------------------------------------- 1 | # 集合容器 2 | -------------------------------------------------------------------------------- /src/safe-guides/coding_practice/control-flow.md: -------------------------------------------------------------------------------- 1 | # 控制流程 2 | -------------------------------------------------------------------------------- /src/safe-guides/coding_practice/data-type.md: -------------------------------------------------------------------------------- 1 | # 数据类型 2 | -------------------------------------------------------------------------------- /src/safe-guides/coding_practice/data-type/bool.md: -------------------------------------------------------------------------------- 1 | # 布尔 2 | -------------------------------------------------------------------------------- /src/safe-guides/coding_practice/data-type/char.md: -------------------------------------------------------------------------------- 1 | # 字符 2 | -------------------------------------------------------------------------------- /src/safe-guides/coding_practice/data-type/int.md: -------------------------------------------------------------------------------- 1 | # 整数 2 | -------------------------------------------------------------------------------- /src/safe-guides/coding_practice/error-handle.md: -------------------------------------------------------------------------------- 1 | # 错误处理 2 | -------------------------------------------------------------------------------- /src/safe-guides/coding_practice/macros/decl.md: -------------------------------------------------------------------------------- 1 | # 声明宏 2 | -------------------------------------------------------------------------------- /src/safe-guides/coding_practice/macros/proc.md: -------------------------------------------------------------------------------- 1 | # 过程宏 2 | -------------------------------------------------------------------------------- /src/safe-guides/coding_practice/memory/box.md: -------------------------------------------------------------------------------- 1 | # Box 类型 2 | -------------------------------------------------------------------------------- /src/safe-guides/coding_practice/no-std.md: -------------------------------------------------------------------------------- 1 | # no-std 2 | -------------------------------------------------------------------------------- /src/safe-guides/coding_practice/security.md: -------------------------------------------------------------------------------- 1 | # 信息安全 2 | -------------------------------------------------------------------------------- /src/safe-guides/coding_practice/threads/lock.md: -------------------------------------------------------------------------------- 1 | # 锁同步 2 | -------------------------------------------------------------------------------- /src/safe-guides/Appendix/best-practice/intro.md: -------------------------------------------------------------------------------- 1 | # I.最佳实践 2 | -------------------------------------------------------------------------------- /src/safe-guides/Appendix/best-practice/qa.md: -------------------------------------------------------------------------------- 1 | # 初学者常见问题Q&A 2 | -------------------------------------------------------------------------------- /src/safe-guides/Appendix/best-practice/tips.md: -------------------------------------------------------------------------------- 1 | # Rust 编程技巧 2 | -------------------------------------------------------------------------------- /src/safe-guides/Appendix/cheat-sheet/Numbers/float.md: -------------------------------------------------------------------------------- 1 | # 浮点数 2 | -------------------------------------------------------------------------------- /src/safe-guides/Appendix/templates/deny.toml.md: -------------------------------------------------------------------------------- 1 | # deny 模板 2 | -------------------------------------------------------------------------------- /src/safe-guides/Appendix/tools/cargo-udeps.md: -------------------------------------------------------------------------------- 1 | # cargo-udeps 2 | -------------------------------------------------------------------------------- /src/safe-guides/coding_practice/async-await.md: -------------------------------------------------------------------------------- 1 | # Async 2 | -------------------------------------------------------------------------------- /src/safe-guides/coding_practice/data-type/array.md: -------------------------------------------------------------------------------- 1 | # 固定长度数组 2 | -------------------------------------------------------------------------------- /src/safe-guides/coding_practice/data-type/enum.md: -------------------------------------------------------------------------------- 1 | # 枚举体 2 | -------------------------------------------------------------------------------- /src/safe-guides/coding_practice/data-type/float.md: -------------------------------------------------------------------------------- 1 | # 浮点数 2 | -------------------------------------------------------------------------------- /src/safe-guides/coding_practice/data-type/slice.md: -------------------------------------------------------------------------------- 1 | # 切片 2 | -------------------------------------------------------------------------------- /src/safe-guides/coding_practice/data-type/struct.md: -------------------------------------------------------------------------------- 1 | # 结构体 2 | -------------------------------------------------------------------------------- /src/safe-guides/coding_practice/data-type/tuple.md: -------------------------------------------------------------------------------- 1 | # 元组 2 | -------------------------------------------------------------------------------- /src/safe-guides/coding_practice/data-type/vec.md: -------------------------------------------------------------------------------- 1 | # 动态数组 2 | -------------------------------------------------------------------------------- /src/safe-guides/coding_practice/memory/drop.md: -------------------------------------------------------------------------------- 1 | # Drop 析构 2 | -------------------------------------------------------------------------------- /src/safe-guides/coding_practice/memory/lifetime.md: -------------------------------------------------------------------------------- 1 | # 生命周期 2 | -------------------------------------------------------------------------------- /src/safe-guides/coding_practice/memory/smart-ptr.md: -------------------------------------------------------------------------------- 1 | # 智能指针 2 | -------------------------------------------------------------------------------- /src/safe-guides/coding_practice/threads/lock-free.md: -------------------------------------------------------------------------------- 1 | # 无锁 2 | -------------------------------------------------------------------------------- /src/safe-guides/coding_practice/unsafe_rust/ffi.md: -------------------------------------------------------------------------------- 1 | # FFi 2 | -------------------------------------------------------------------------------- /src/safe-guides/coding_practice/unsafe_rust/io.md: -------------------------------------------------------------------------------- 1 | # I/O 2 | -------------------------------------------------------------------------------- /src/safe-guides/coding_practice/unsafe_rust/mem.md: -------------------------------------------------------------------------------- 1 | # 内存 2 | -------------------------------------------------------------------------------- /src/safe-guides/coding_practice/unsafe_rust/union.md: -------------------------------------------------------------------------------- 1 | # 联合体 2 | -------------------------------------------------------------------------------- /src/safe-guides/coding_practice/variables.md: -------------------------------------------------------------------------------- 1 | # Local Const 2 | -------------------------------------------------------------------------------- /src/safe-guides/Appendix/cheat-sheet/README.md: -------------------------------------------------------------------------------- 1 | # F.Cheat Sheet 2 | -------------------------------------------------------------------------------- /src/safe-guides/Appendix/templates/clippy.toml.md: -------------------------------------------------------------------------------- 1 | # clippy 模板 2 | -------------------------------------------------------------------------------- /src/safe-guides/Appendix/templates/rustfmt.toml.md: -------------------------------------------------------------------------------- 1 | # rustfmt 模板 2 | -------------------------------------------------------------------------------- /src/safe-guides/Appendix/tools/noisy-clippy.md: -------------------------------------------------------------------------------- 1 | # noisy-clippy 2 | -------------------------------------------------------------------------------- /src/safe-guides/coding_practice/fn-design.md: -------------------------------------------------------------------------------- 1 | # Function Design 2 | -------------------------------------------------------------------------------- /src/safe-guides/coding_practice/unsafe_rust.md: -------------------------------------------------------------------------------- 1 | # Unsafe Rust 2 | -------------------------------------------------------------------------------- /src/safe-guides/coding_practice/unsafe_rust/raw_ptr.md: -------------------------------------------------------------------------------- 1 | # 裸指针操作 2 | -------------------------------------------------------------------------------- /src/safe-guides/code_style/fmt/P.FMT.09.md: -------------------------------------------------------------------------------- 1 | # P.FMT.09 不同的场景，使用不同的空格风格 2 | -------------------------------------------------------------------------------- /src/safe-guides/code_style/fmt/P.FMT.12.md: -------------------------------------------------------------------------------- 1 | # P.FMT.12 声明宏分支应该具有良好的可读性 2 | -------------------------------------------------------------------------------- /src/safe-guides/coding_practice/cargo.md: -------------------------------------------------------------------------------- 1 | # Cargo package management 2 | -------------------------------------------------------------------------------- /src/safe-guides/coding_practice/macros/P.MAC.01.md: -------------------------------------------------------------------------------- 1 | # P.MAC.01 不要轻易使用宏 2 | -------------------------------------------------------------------------------- /src/safe-guides/coding_practice/traits/std-builtin.md: -------------------------------------------------------------------------------- 1 | # 标准库内置 trait 2 | -------------------------------------------------------------------------------- /src/safe-guides/coding_practice/traits/trait-object.md: -------------------------------------------------------------------------------- 1 | # trait 对象 2 | -------------------------------------------------------------------------------- /src/safe-guides/coding_practice/unsafe_rust/safe_abstract.md: -------------------------------------------------------------------------------- 1 | # 安全抽象 2 | -------------------------------------------------------------------------------- /src/safe-guides/code_style/fmt/P.FMT.10.md: -------------------------------------------------------------------------------- 1 | # P.FMT.10 match 分支应该具有良好的可读性 2 | -------------------------------------------------------------------------------- /src/safe-guides/code_style/fmt/P.FMT.11.md: -------------------------------------------------------------------------------- 1 | # P.FMT.11 导入模块分组应该具有良好的可读性 2 | -------------------------------------------------------------------------------- /src/safe-guides/code_style/fmt/P.FMT.13.md: -------------------------------------------------------------------------------- 1 | # P.FMT.13 具名结构体字段初始化时不要省略字段名 2 | -------------------------------------------------------------------------------- /src/safe-guides/code_style/fmt/P.FMT.15.md: -------------------------------------------------------------------------------- 1 | # P.FMT.15 解构元组的时候允许使用..来指代剩余元素 2 | -------------------------------------------------------------------------------- /src/safe-guides/coding_practice/cargo/P.CAR.02.md: -------------------------------------------------------------------------------- 1 | # P.CAR.02 不要滥用 Features 2 | -------------------------------------------------------------------------------- /src/safe-guides/coding_practice/consts/G.CNS.02.md: -------------------------------------------------------------------------------- 1 | # G.CNS.02 不应断言常量布尔类型 2 | -------------------------------------------------------------------------------- /src/safe-guides/coding_practice/expr/G.EXP.04.md: -------------------------------------------------------------------------------- 1 | # G.EXP.04 自增或自减运算使用+=或-= 2 | -------------------------------------------------------------------------------- /src/safe-guides/coding_practice/generic/P.GEN.01.md: -------------------------------------------------------------------------------- 1 | # P.GEN.01 用泛型来抽象公共语义 2 | -------------------------------------------------------------------------------- /src/safe-guides/coding_practice/unsafe_rust/glossary.md: -------------------------------------------------------------------------------- 1 | # Unsafe 代码术语指南 2 | -------------------------------------------------------------------------------- /src/safe-guides/code_style/fmt/P.FMT.14.md: -------------------------------------------------------------------------------- 1 | # P.FMT.14 extern 外部函数需要显式指定 C-ABI 2 | -------------------------------------------------------------------------------- /src/safe-guides/code_style/fmt/P.FMT.16.md: -------------------------------------------------------------------------------- 1 | # P.FMT.16 不要将派生宏中多个不相关的特质合并为同一行 2 | -------------------------------------------------------------------------------- /src/safe-guides/coding_practice/async-await/G.ASY.04.md: -------------------------------------------------------------------------------- 1 | # G.ASY.04 避免定义不必要的异步函数 2 | -------------------------------------------------------------------------------- /src/safe-guides/coding_practice/consts/G.CNS.03.md: -------------------------------------------------------------------------------- 1 | # G.CNS.03 不应将内部可变性容器声明为常量 2 | -------------------------------------------------------------------------------- /src/safe-guides/coding_practice/control-flow/P.CTF.01.md: -------------------------------------------------------------------------------- 1 | # P.CTF.01 避免滥用迭代器 2 | -------------------------------------------------------------------------------- /src/safe-guides/coding_practice/expr/G.EXP.02.md: -------------------------------------------------------------------------------- 1 | # G.EXP.02 不宜在比较中使用不兼容的位掩码 2 | -------------------------------------------------------------------------------- /src/safe-guides/coding_practice/expr/G.EXP.05.md: -------------------------------------------------------------------------------- 1 | # G.EXP.05 使用括号来清楚表示表达式的计算顺序 2 | -------------------------------------------------------------------------------- /src/safe-guides/coding_practice/expr/G.EXP.06.md: -------------------------------------------------------------------------------- 1 | # G.EXP.06 避免在比较中添加无用的掩码操作 2 | -------------------------------------------------------------------------------- /src/safe-guides/coding_practice/generic/G.GEN.01.md: -------------------------------------------------------------------------------- 1 | # G.GEN.01 不要在泛型位置上使用内建类型 2 | -------------------------------------------------------------------------------- /src/safe-guides/coding_practice/macros/G.MAC.01.md: -------------------------------------------------------------------------------- 1 | # G.MAC.01 dbg!() 宏只应该用于调试代码 2 | -------------------------------------------------------------------------------- /src/safe-guides/coding_practice/module/G.MOD.03.md: -------------------------------------------------------------------------------- 1 | # G.MOD.03 导入模块不要随便使用 通配符* 2 | -------------------------------------------------------------------------------- /src/safe-guides/coding_practice/module/P.MOD.01.md: -------------------------------------------------------------------------------- 1 | # P.MOD.01 合理控制对外接口和模块之间的可见性 2 | -------------------------------------------------------------------------------- /src/safe-guides/coding_practice/variables/G.VAR.03.md: -------------------------------------------------------------------------------- 1 | # G.VAR.03 变量遮蔽功能应当合理使用 2 | -------------------------------------------------------------------------------- /src/safe-guides/code_style/naming/G.NAM.01.md: -------------------------------------------------------------------------------- 1 | # G.NAM.01 Use a uniform naming style 2 | -------------------------------------------------------------------------------- /src/safe-guides/coding_practice/async-await/G.ASY.05.md: -------------------------------------------------------------------------------- 1 | # G.ASY.05 避免在异步处理过程中包含阻塞操作 2 | -------------------------------------------------------------------------------- /src/safe-guides/coding_practice/cargo/P.CAR.01.md: -------------------------------------------------------------------------------- 1 | # P.CAR.01 应该尽量把项目划分为合理的 crate 组合 2 | -------------------------------------------------------------------------------- /src/safe-guides/coding_practice/control-flow/P.CTF.02.md: -------------------------------------------------------------------------------- 1 | # P.CTF.02 优先使用模式匹配而非判断后再取值 2 | -------------------------------------------------------------------------------- /src/safe-guides/coding_practice/data-type/G.TYP.02.md: -------------------------------------------------------------------------------- 1 | # G.TYP.02 数字字面量在使用的时候应该明确标注类型 2 | -------------------------------------------------------------------------------- /src/safe-guides/coding_practice/macros/G.MAC.02.md: -------------------------------------------------------------------------------- 1 | # G.MAC.02 使用宏时应该考虑宏展开会让编译文件膨胀的影响 2 | -------------------------------------------------------------------------------- /src/safe-guides/coding_practice/macros/proc/P.MAC.PRO.03.md: -------------------------------------------------------------------------------- 1 | # P.MAC.PRO.03 保证过程宏的卫生性 2 | -------------------------------------------------------------------------------- /src/safe-guides/coding_practice/macros/proc/P.MAC.PRO.04.md: -------------------------------------------------------------------------------- 1 | # P.MAC.PRO.04 给出正确的错误位置 2 | -------------------------------------------------------------------------------- /src/safe-guides/coding_practice/memory/drop/G.MEM.DRP.01.md: -------------------------------------------------------------------------------- 1 | # G.MEM.DRP.01 要注意防范内存泄漏 2 | -------------------------------------------------------------------------------- /src/safe-guides/coding_practice/module/G.MOD.04.md: -------------------------------------------------------------------------------- 1 | # G.MOD.04 一个项目中应该避免使用不同的模块布局风格 2 | -------------------------------------------------------------------------------- /src/safe-guides/coding_practice/strings/G.STR.02.md: -------------------------------------------------------------------------------- 1 | # G.STR.02 在追加字符串时使用push_str方法 2 | -------------------------------------------------------------------------------- /src/safe-guides/coding_practice/strings/P.STR.01.md: -------------------------------------------------------------------------------- 1 | # P.STR.01 处理字符串元素时优先按字节处理而非字符 2 | -------------------------------------------------------------------------------- /src/safe-guides/coding_practice/strings/P.STR.05.md: -------------------------------------------------------------------------------- 1 | # P.STR.05 在拼接字符串时，优先使用format! 2 | -------------------------------------------------------------------------------- /src/safe-guides/coding_practice/variables/G.VAR.02.md: -------------------------------------------------------------------------------- 1 | # G.VAR.02 不应使用非 ASCII 字符作为标识符 2 | -------------------------------------------------------------------------------- /src/safe-guides/coding_practice/variables/G.VAR.04.md: -------------------------------------------------------------------------------- 1 | # G.VAR.04 避免因局部变量过大而导致的大量栈分配 2 | -------------------------------------------------------------------------------- /src/safe-guides/coding_practice/variables/P.VAR.01.md: -------------------------------------------------------------------------------- 1 | # P.VAR.01 一般情况下避免先声明可变变量再赋值 2 | -------------------------------------------------------------------------------- /src/safe-guides/coding_practice/variables/P.VAR.02.md: -------------------------------------------------------------------------------- 1 | # P.VAR.02 利用变量遮蔽功能保证变量安全使用 2 | -------------------------------------------------------------------------------- /src/safe-guides/coding_practice/cargo/G.CAR.03.md: -------------------------------------------------------------------------------- 1 | # G.CAR.03 Feature 命名应该避免否定式或多余的前后缀 2 | -------------------------------------------------------------------------------- /src/safe-guides/coding_practice/cargo/G.CAR.04.md: -------------------------------------------------------------------------------- 1 | # G.CAR.04 Cargo.toml 中依赖包版本不应使用通配符 2 | -------------------------------------------------------------------------------- /src/safe-guides/coding_practice/cargo/P.CAR.04.md: -------------------------------------------------------------------------------- 1 | # P.CAR.04 如果可能的话，使用 cfg! 来代替 #[cfg] 2 | -------------------------------------------------------------------------------- /src/safe-guides/coding_practice/consts/G.CNS.01.md: -------------------------------------------------------------------------------- 1 | # G.CNS.01 对于科学计算中涉及浮点数近似值的常量宜使用预定义常量 2 | -------------------------------------------------------------------------------- /src/safe-guides/coding_practice/data-type/G.TYP.01.md: -------------------------------------------------------------------------------- 1 | # G.TYP.01 类型转换尽可能使用安全的转换函数代替 as 2 | -------------------------------------------------------------------------------- /src/safe-guides/coding_practice/data-type/bool/G.TYP.BOL.06.md: -------------------------------------------------------------------------------- 1 | # G.TYP.BOL.06 不应使用数字代替布尔值 2 | -------------------------------------------------------------------------------- /src/safe-guides/coding_practice/data-type/enum/G.TYP.ENM.02.md: -------------------------------------------------------------------------------- 1 | # G.TYP.ENM.02 不应自行创建空枚举 2 | -------------------------------------------------------------------------------- /src/safe-guides/coding_practice/data-type/vec/G.TYP.VEC.01.md: -------------------------------------------------------------------------------- 1 | # G.TYP.VEC.01 禁止访问未初始化的数组 2 | -------------------------------------------------------------------------------- /src/safe-guides/coding_practice/data-type/vec/P.TYP.VEC.01.md: -------------------------------------------------------------------------------- 1 | # P.TYP.VEC.01 非必要时不宜使用动态数组 2 | -------------------------------------------------------------------------------- /src/safe-guides/coding_practice/expr/G.EXP.01.md: -------------------------------------------------------------------------------- 1 | # G.EXP.01 当需要对表达式求值后重新赋值时，宜使用复合赋值模式 2 | -------------------------------------------------------------------------------- /src/safe-guides/coding_practice/expr/G.EXP.03.md: -------------------------------------------------------------------------------- 1 | # G.EXP.03 不应利用数组表达式的边界检查来 Panic，而应使用断言 2 | -------------------------------------------------------------------------------- /src/safe-guides/coding_practice/generic/P.GEN.02.md: -------------------------------------------------------------------------------- 1 | # P.GEN.02 不要随便使用 impl Trait 语法替代泛型限定 2 | -------------------------------------------------------------------------------- /src/safe-guides/coding_practice/macros/P.MAC.02.md: -------------------------------------------------------------------------------- 1 | # P.MAC.02 实现宏语法的时候，应该尽量贴近 Rust 语法 2 | -------------------------------------------------------------------------------- /src/safe-guides/coding_practice/macros/decl/P.MAC.DCL.04.md: -------------------------------------------------------------------------------- 1 | # P.MAC.DCL.04 匹配规则要精准，不要模糊不清 2 | -------------------------------------------------------------------------------- /src/safe-guides/coding_practice/macros/decl/P.MAC.DCL.07.md: -------------------------------------------------------------------------------- 1 | # P.MAC.DCL.07 确保在宏定义之后再去调用宏 2 | -------------------------------------------------------------------------------- /src/safe-guides/coding_practice/module/P.MOD.02.md: -------------------------------------------------------------------------------- 1 | # P.MOD.02 将模块的测试移动到单独的文件，有助于增加编译速度 2 | -------------------------------------------------------------------------------- /src/safe-guides/coding_practice/no-std/P.EMB.01.md: -------------------------------------------------------------------------------- 1 | # P.EMB.01 no-std 下必须定义一个Panic行为以确保安全 2 | -------------------------------------------------------------------------------- /src/safe-guides/coding_practice/no-std/P.EMB.02.md: -------------------------------------------------------------------------------- 1 | # P.EMB.02 no-std 下要确保程序中的类型有正确的内存布局 2 | -------------------------------------------------------------------------------- /src/safe-guides/coding_practice/others/G.OTH.02.md: -------------------------------------------------------------------------------- 1 | # G.OTH.01 使用标准库中对应的方法计算秒级、毫秒级、微秒级的时间 2 | -------------------------------------------------------------------------------- /src/safe-guides/coding_practice/security/P.SEC.01.md: -------------------------------------------------------------------------------- 1 | # P.SEC.01 使用第三方库的时候要确保可信的依赖，小心供应链攻击 2 | -------------------------------------------------------------------------------- /src/safe-guides/coding_practice/strings/P.STR.04.md: -------------------------------------------------------------------------------- 1 | # P.STR.04 只在合适的场景下，使用正则表达式第三方库regex 2 | -------------------------------------------------------------------------------- /src/safe-guides/coding_practice/traits/P.TRA.01.md: -------------------------------------------------------------------------------- 1 | # P.TRA.01 使用 trait 时要注意 trait 一致性规则 2 | -------------------------------------------------------------------------------- /src/safe-guides/code_style/fmt/P.FMT.01.md: -------------------------------------------------------------------------------- 1 | # P.FMT.01 Automatic code formatting with rustfmt 2 | -------------------------------------------------------------------------------- /src/safe-guides/coding_practice/cargo/G.CAR.02.md: -------------------------------------------------------------------------------- 1 | # G.CAR.02 Crate 的 Cargo.toml 中应该包含必要的元信息 2 | -------------------------------------------------------------------------------- /src/safe-guides/coding_practice/data-type/array/G.TYP.ARR.02.md: -------------------------------------------------------------------------------- 1 | # G.TYP.ARR.02 使用数组索引时禁止越界访问 2 | -------------------------------------------------------------------------------- /src/safe-guides/coding_practice/data-type/bool/G.TYP.BOL.01.md: -------------------------------------------------------------------------------- 1 | # G.TYP.BOL.01 不应将布尔值和布尔字面量进行比较 2 | -------------------------------------------------------------------------------- /src/safe-guides/coding_practice/data-type/bool/G.TYP.BOL.03.md: -------------------------------------------------------------------------------- 1 | # G.TYP.BOL.03 不应将数字类型转换为布尔值 2 | -------------------------------------------------------------------------------- /src/safe-guides/coding_practice/data-type/bool/G.TYP.BOL.04.md: -------------------------------------------------------------------------------- 1 | # G.TYP.BOL.04 禁止在if表达式条件中使用块结构 2 | -------------------------------------------------------------------------------- /src/safe-guides/coding_practice/data-type/char/G.TYP.CHR.01.md: -------------------------------------------------------------------------------- 1 | # G.TYP.CHR.01 不应将字符字面量强制转换为 u8 2 | -------------------------------------------------------------------------------- /src/safe-guides/coding_practice/data-type/enum/G.TYP.ENM.06.md: -------------------------------------------------------------------------------- 1 | # G.TYP.ENM.06 Enum内变体的大小差异不宜过大 2 | -------------------------------------------------------------------------------- /src/safe-guides/coding_practice/data-type/int/G.TYP.INT.03.md: -------------------------------------------------------------------------------- 1 | # G.TYP.INT.03 对负数取模计算的时候不应使用 % 2 | -------------------------------------------------------------------------------- /src/safe-guides/coding_practice/data-type/slice/P.TYP.SLC.01.md: -------------------------------------------------------------------------------- 1 | # P.TYP.SLC.01 宜使用切片迭代器来代替手工索引 2 | -------------------------------------------------------------------------------- /src/safe-guides/coding_practice/data-type/tuple/G.TYP.TUP.01.md: -------------------------------------------------------------------------------- 1 | # G.TYP.TUP.01 使用元组时，其元素不宜超过3个 2 | -------------------------------------------------------------------------------- /src/safe-guides/coding_practice/generic/P.GEN.03.md: -------------------------------------------------------------------------------- 1 | # P.GEN.03 不要使用太多泛型参数和 trait 限定，否则会增长编译时间 2 | -------------------------------------------------------------------------------- /src/safe-guides/coding_practice/macros/decl/P.MAC.DCL.01.md: -------------------------------------------------------------------------------- 1 | # P.MAC.DCL.01 不要将声明宏内的变量作为外部变量使用 2 | -------------------------------------------------------------------------------- /src/safe-guides/coding_practice/macros/decl/P.MAC.DCL.03.md: -------------------------------------------------------------------------------- 1 | # P.MAC.DCL.03 不要在片段分类符跟随它不匹配的符号 2 | -------------------------------------------------------------------------------- /src/safe-guides/coding_practice/macros/decl/P.MAC.DCL.06.md: -------------------------------------------------------------------------------- 1 | # P.MAC.DCL.06 当宏需要接收 self 时需要注意 2 | -------------------------------------------------------------------------------- /src/safe-guides/coding_practice/macros/proc/P.MAC.PRO.01.md: -------------------------------------------------------------------------------- 1 | # P.MAC.PRO.01 不要使用过程宏来规避静态分析检查 2 | -------------------------------------------------------------------------------- /src/safe-guides/coding_practice/macros/proc/P.MAC.PRO.02.md: -------------------------------------------------------------------------------- 1 | # P.MAC.PRO.02 实现过程宏时要对关键特性增加测试 2 | -------------------------------------------------------------------------------- /src/safe-guides/coding_practice/module/G.MOD.01.md: -------------------------------------------------------------------------------- 1 | # G.MOD.01 使用导入模块中的类型或函数，在某些情况下需要带模块名前缀 2 | -------------------------------------------------------------------------------- /src/safe-guides/coding_practice/module/G.MOD.05.md: -------------------------------------------------------------------------------- 1 | # G.MOD.05 不要在私有模块中设置其内部类型或函数方法为 pub(crate) 2 | -------------------------------------------------------------------------------- /src/safe-guides/coding_practice/strings/G.STR.01.md: -------------------------------------------------------------------------------- 1 | # G.STR.01 在实现Display特质时不应调用to_string()方法 2 | -------------------------------------------------------------------------------- /src/safe-guides/coding_practice/strings/G.STR.04.md: -------------------------------------------------------------------------------- 1 | # G.STR.04 需要辨别字符串的字符开头或结尾字符时，不应按字符迭代比较 2 | -------------------------------------------------------------------------------- /src/safe-guides/coding_practice/unsafe_rust/G.UNS.01.md: -------------------------------------------------------------------------------- 1 | # G.UNS.01 不宜为带有 unsafe 命名的类型或方法创建别名 2 | -------------------------------------------------------------------------------- /src/safe-guides/coding_practice/unsafe_rust/P.UNS.02.md: -------------------------------------------------------------------------------- 1 | # P.UNS.02 不要为了提升性能而盲目使用 Unsafe Rust 2 | -------------------------------------------------------------------------------- /src/safe-guides/coding_practice/unsafe_rust/ffi/P.UNS.FFI.08.md: -------------------------------------------------------------------------------- 1 | # P.UNS.FFI.08 FFi 中要进行合理的错误处理 2 | -------------------------------------------------------------------------------- /src/safe-guides/coding_practice/variables/G.VAR.01.md: -------------------------------------------------------------------------------- 1 | # G.VAR.01 以解构元组方式定义超过四个变量时不应使用太多无意义变量名 2 | -------------------------------------------------------------------------------- /src/safe-guides/code_style/fmt/P.FMT.02.md: -------------------------------------------------------------------------------- 1 | # P.FMT.02 Use spaces instead of tabs for indentation 2 | -------------------------------------------------------------------------------- /src/safe-guides/coding_practice/async-await/G.ASY.02.md: -------------------------------------------------------------------------------- 1 | # G.ASY.02 在跨 await 调用中，需要对其持有的同步互斥锁进行处理 2 | -------------------------------------------------------------------------------- /src/safe-guides/coding_practice/async-await/P.ASY.01.md: -------------------------------------------------------------------------------- 1 | # P.ASY.01 异步编程并不适合所有场景，计算密集型场景应该考虑同步编程 2 | -------------------------------------------------------------------------------- /src/safe-guides/coding_practice/cargo/P.CAR.03.md: -------------------------------------------------------------------------------- 1 | # P.CAR.03 使用 cargo features 来代替 --cfg 条件编译参数 2 | -------------------------------------------------------------------------------- /src/safe-guides/coding_practice/data-type/P.TYP.01.md: -------------------------------------------------------------------------------- 1 | # P.TYP.01 必要时，应使类型可以表达更明确的语义，而不是只是直接使用原生类型 2 | -------------------------------------------------------------------------------- /src/safe-guides/coding_practice/data-type/array/G.TYP.ARR.01.md: -------------------------------------------------------------------------------- 1 | # G.TYP.ARR.01 创建大全局数组时宜使用静态变量而非常量 2 | -------------------------------------------------------------------------------- /src/safe-guides/coding_practice/data-type/enum/G.TYP.ENM.01.md: -------------------------------------------------------------------------------- 1 | # G.TYP.ENM.01 合理使用map和and_then方法 2 | -------------------------------------------------------------------------------- /src/safe-guides/coding_practice/data-type/float/G.TYP.FLT.04.md: -------------------------------------------------------------------------------- 1 | # G.TYP.FLT.04 宜使用Rust内置方法处理浮点数计算 2 | -------------------------------------------------------------------------------- /src/safe-guides/coding_practice/data-type/int/G.TYP.INT.02.md: -------------------------------------------------------------------------------- 1 | # G.TYP.INT.02 避免在有符号整数和无符号整数之间进行强制转换 2 | -------------------------------------------------------------------------------- /src/safe-guides/coding_practice/data-type/slice/P.TYP.SLC.02.md: -------------------------------------------------------------------------------- 1 | # P.TYP.SLC.02 宜使用切片模式来提升代码的可读性 2 | -------------------------------------------------------------------------------- /src/safe-guides/coding_practice/generic/P.GEN.04.md: -------------------------------------------------------------------------------- 1 | # P.GEN.04 为泛型类型实现方法时，impl 中声明的泛型类型参数一定要被用到 2 | -------------------------------------------------------------------------------- /src/safe-guides/coding_practice/macros/decl/P.MAC.DCL.02.md: -------------------------------------------------------------------------------- 1 | # P.MAC.DCL.02 在编写多个宏规则时，应该先从匹配粒度最小的开始写 2 | -------------------------------------------------------------------------------- /src/safe-guides/coding_practice/macros/proc/P.MAC.PRO.06.md: -------------------------------------------------------------------------------- 1 | # P.MAC.PRO.06 build.rs 生成的代码要保证没有任何警告 2 | -------------------------------------------------------------------------------- /src/safe-guides/coding_practice/memory/box/G.MEM.BOX.01.md: -------------------------------------------------------------------------------- 1 | # G.MEM.BOX.01 一般情况下，不应直接对 Box 进行借用 2 | -------------------------------------------------------------------------------- /src/safe-guides/coding_practice/memory/box/G.MEM.BOX.03.md: -------------------------------------------------------------------------------- 1 | # G.MEM.BOX.03 一般情况下，不应直接对栈分配类型进行 Box 装箱 2 | -------------------------------------------------------------------------------- /src/safe-guides/coding_practice/memory/lifetime/P.MEM.LFT.01.md: -------------------------------------------------------------------------------- 1 | # P.MEM.LFT.01 生命周期参数命名尽量有意义且简洁 2 | -------------------------------------------------------------------------------- /src/safe-guides/coding_practice/others/G.OTH.01.md: -------------------------------------------------------------------------------- 1 | # G.OTH.01 对于某些场景下不建议使用的方法可以通过配置 clippy.toml 来拒绝 2 | -------------------------------------------------------------------------------- /src/safe-guides/coding_practice/strings/G.STR.05.md: -------------------------------------------------------------------------------- 1 | # G.STR.05 对字符串按指定位置进行切片的时候需要小心破坏其 UTF-8 编码 2 | -------------------------------------------------------------------------------- /src/safe-guides/coding_practice/strings/P.STR.02.md: -------------------------------------------------------------------------------- 1 | # P.STR.02 创建字符串时，宜预先分配大约足够的容量来避免后续操作中产生多次分配 2 | -------------------------------------------------------------------------------- /src/safe-guides/coding_practice/strings/P.STR.03.md: -------------------------------------------------------------------------------- 1 | # P.STR.03 在使用内建字符串处理函数或方法的时候，应注意避免隐藏的嵌套迭代或多次迭代 2 | -------------------------------------------------------------------------------- /src/safe-guides/coding_practice/threads/lock-free/P.MTH.LKF.01.md: -------------------------------------------------------------------------------- 1 | # P.MTH.LKF.01 除非必要，否则建议使用同步锁 2 | -------------------------------------------------------------------------------- /src/safe-guides/coding_practice/threads/lock-free/P.MTH.LKF.02.md: -------------------------------------------------------------------------------- 1 | # P.MTH.LKF.02 使用无锁编程时，需要合理选择内存顺序 2 | -------------------------------------------------------------------------------- /src/safe-guides/coding_practice/threads/lock/G.MTH.LCK.01.md: -------------------------------------------------------------------------------- 1 | # G.MTH.LCK.01 对布尔或引用并发访问应该使用原子类型而非互斥锁 2 | -------------------------------------------------------------------------------- /src/safe-guides/coding_practice/threads/lock/P.MTH.LCK.01.md: -------------------------------------------------------------------------------- 1 | # P.MTH.LCK.01 多线程下要注意识别锁争用的情况，避免死锁 2 | -------------------------------------------------------------------------------- /src/safe-guides/coding_practice/traits/std-builtin/G.TRA.BLN.02.md: -------------------------------------------------------------------------------- 1 | # G.TRA.BLN.02 不要为迭代器实现Copy 特质 2 | -------------------------------------------------------------------------------- /src/safe-guides/coding_practice/traits/std-builtin/G.TRA.BLN.08.md: -------------------------------------------------------------------------------- 1 | # G.TRA.BLN.08 实现 From 而不是 Into 2 | -------------------------------------------------------------------------------- /src/safe-guides/coding_practice/traits/trait-object/P.TRA.OBJ.02.md: -------------------------------------------------------------------------------- 1 | # P.TRA.OBJ.02 除非必要，避免自定义虚表 2 | -------------------------------------------------------------------------------- /src/safe-guides/coding_practice/unsafe_rust/P.UNS.01.md: -------------------------------------------------------------------------------- 1 | # P.UNS.01 不要为了逃避编译器安全检查而滥用 Unsafe Rust 2 | -------------------------------------------------------------------------------- /src/safe-guides/coding_practice/unsafe_rust/ffi/P.UNS.FFI.07.md: -------------------------------------------------------------------------------- 1 | # P.UNS.FFI.07 不要为任何传出外部的类型实现 Drop 2 | -------------------------------------------------------------------------------- /src/safe-guides/coding_practice/unsafe_rust/ffi/P.UNS.FFI.13.md: -------------------------------------------------------------------------------- 1 | # P.UNS.FFI.13 自定义数据类型要保证一致的数据布局 2 | -------------------------------------------------------------------------------- /src/safe-guides/coding_practice/unsafe_rust/ffi/P.UNS.FFI.14.md: -------------------------------------------------------------------------------- 1 | # P.UNS.FFI.14 在 FFi 中使用的类型应该拥有稳定布局 2 | -------------------------------------------------------------------------------- /src/safe-guides/coding_practice/unsafe_rust/ffi/P.UNS.FFI.15.md: -------------------------------------------------------------------------------- 1 | # P.UNS.FFI.15 从外部传入的不健壮类型的外部值要进行检查 2 | -------------------------------------------------------------------------------- /src/safe-guides/coding_practice/unsafe_rust/mem/P.UNS.MEM.02.md: -------------------------------------------------------------------------------- 1 | # P.UNS.MEM.02 不能修改其它进程或动态库的内存变量 2 | -------------------------------------------------------------------------------- /src/safe-guides/coding_practice/unsafe_rust/mem/P.UNS.MEM.05.md: -------------------------------------------------------------------------------- 1 | # P.UNS.MEM.05 如果需要使用位域，推荐使用第三方库 2 | -------------------------------------------------------------------------------- /src/safe-guides/coding_practice/unsafe_rust/raw_ptr/P.UNS.PTR.01.md: -------------------------------------------------------------------------------- 1 | # P.UNS.PTR.01 不要将裸指针在多线程间共享 2 | -------------------------------------------------------------------------------- /src/safe-guides/coding_practice/async-await/G.ASY.03.md: -------------------------------------------------------------------------------- 1 | # G.ASY.03 在跨 await 调用中，需要对其持有 RefCell 的引用进行处理 2 | -------------------------------------------------------------------------------- /src/safe-guides/coding_practice/consts/G.CNS.05.md: -------------------------------------------------------------------------------- 1 | # G.CNS.05 Should use const fn as much as possible 2 | -------------------------------------------------------------------------------- /src/safe-guides/coding_practice/control-flow/G.CTF.02.md: -------------------------------------------------------------------------------- 1 | # G.CTF.02 if条件表达式分支中如果包含了else if分支也应该包含else分支 2 | -------------------------------------------------------------------------------- /src/safe-guides/coding_practice/control-flow/G.CTF.03.md: -------------------------------------------------------------------------------- 1 | # G.CTF.03 如果要通过 if 条件表达式来判断是否 Panic，请优先使用断言 2 | -------------------------------------------------------------------------------- /src/safe-guides/coding_practice/control-flow/G.CTF.04.md: -------------------------------------------------------------------------------- 1 | # G.CTF.04 在 Match 分支的 Guard 语句中不要使用带有副作用的条件表达式 2 | -------------------------------------------------------------------------------- /src/safe-guides/coding_practice/data-type/G.TYP.03.md: -------------------------------------------------------------------------------- 1 | # G.TYP.03 不要用数字类型边界值判断能否安全转换，而应使用 try_from 方法 2 | -------------------------------------------------------------------------------- /src/safe-guides/coding_practice/data-type/float/G.TYP.FLT.02.md: -------------------------------------------------------------------------------- 1 | # G.TYP.FLT.02 从任何数字类型转换为浮点类型时注意避免损失精度 2 | -------------------------------------------------------------------------------- /src/safe-guides/coding_practice/data-type/int/G.TYP.INT.01.md: -------------------------------------------------------------------------------- 1 | # G.TYP.INT.01 在用整数计算的时候需要考虑整数溢出、回绕和截断的风险 2 | -------------------------------------------------------------------------------- /src/safe-guides/coding_practice/data-type/struct/G.TYP.SCT.03.md: -------------------------------------------------------------------------------- 1 | # G.TYP.SCT.03 宜使用结构体功能更新语法来提升代码可读性 2 | -------------------------------------------------------------------------------- /src/safe-guides/coding_practice/error-handle/G.ERR.02.md: -------------------------------------------------------------------------------- 1 | # G.ERR.02 不要滥用 expect，请考虑用 unwrap_or_ 系列方法代替 2 | -------------------------------------------------------------------------------- /src/safe-guides/coding_practice/error-handle/P.ERR.01.md: -------------------------------------------------------------------------------- 1 | # P.ERR.01 当传入函数的参数值因为超出某种限制可能会导致函数调用失败，应该使用断言 2 | -------------------------------------------------------------------------------- /src/safe-guides/coding_practice/io/G.FIO.01.md: -------------------------------------------------------------------------------- 1 | # G.FIO.01 文件读取建议使用 BufReader/BufWriter 来代替 Reader/Write 2 | -------------------------------------------------------------------------------- /src/safe-guides/coding_practice/macros/decl/P.MAC.DCL.08.md: -------------------------------------------------------------------------------- 1 | # P.MAC.DCL.08 同一个 crate 内定义的宏相互调用时，需要注意卫生性 2 | -------------------------------------------------------------------------------- /src/safe-guides/coding_practice/macros/proc/P.MAC.PRO.05.md: -------------------------------------------------------------------------------- 1 | # P.MAC.PRO.05 代码生成要按情况选择使用过程宏还是 build.rs 2 | -------------------------------------------------------------------------------- /src/safe-guides/coding_practice/memory/lifetime/P.MEM.LFT.02.md: -------------------------------------------------------------------------------- 1 | # P.MEM.LFT.02 通常需要显式地标注生命周期，而非利用编译器推断 2 | -------------------------------------------------------------------------------- /src/safe-guides/coding_practice/module/G.MOD.02.md: -------------------------------------------------------------------------------- 1 | # G.MOD.02 如果是作为库供别人使用，在 lib.rs中重新导出对外类型、函数和 trait 等 2 | -------------------------------------------------------------------------------- /src/safe-guides/coding_practice/security/G.SEC.01.md: -------------------------------------------------------------------------------- 1 | # G.SEC.01 代码中不要出现非法 Unicode 字符，也要防范非法 Unicode 字符 2 | -------------------------------------------------------------------------------- /src/safe-guides/coding_practice/traits/std-builtin/G.TRA.BLN.10.md: -------------------------------------------------------------------------------- 1 | # G.TRA.BLN.10 不要随便使用Deref特质来模拟继承 2 | -------------------------------------------------------------------------------- /src/safe-guides/coding_practice/traits/std-builtin/P.TRA.BLN.01.md: -------------------------------------------------------------------------------- 1 | # P.TRA.BLN.01 在实现Borrow特质时，需要注意一致性 2 | -------------------------------------------------------------------------------- /src/safe-guides/coding_practice/unsafe_rust/io/P.UNS.FIO.01.md: -------------------------------------------------------------------------------- 1 | # P.UNS.FIO.01 在使用原始句柄的时候，要注意 I/O 安全性 2 | -------------------------------------------------------------------------------- /src/safe-guides/coding_practice/unsafe_rust/mem/P.UNS.MEM.01.md: -------------------------------------------------------------------------------- 1 | # P.UNS.MEM.01 要注意选择合适的结构体、元组、枚举的数据布局 2 | -------------------------------------------------------------------------------- /src/safe-guides/coding_practice/unsafe_rust/raw_ptr/G.UNS.PTR.02.md: -------------------------------------------------------------------------------- 1 | # G.UNS.PTR.02 禁止将不可变指针手工转换为可变指针 2 | -------------------------------------------------------------------------------- /src/safe-guides/coding_practice/unsafe_rust/union/P.UNS.UNI.01.md: -------------------------------------------------------------------------------- 1 | # P.UNS.UNI.01 除了与 C 交互，尽量不要使用 Union 2 | -------------------------------------------------------------------------------- /src/safe-guides/coding_practice/unsafe_rust/union/P.UNS.UNI.02.md: -------------------------------------------------------------------------------- 1 | # P.UNS.UNI.02 不要把联合体的不同变体用在不同生命周期内 2 | -------------------------------------------------------------------------------- /src/safe-guides/code_style/fmt/P.FMT.03.md: -------------------------------------------------------------------------------- 1 | # P.FMT.03 The maximum width of line spacing is one blank line 2 | -------------------------------------------------------------------------------- /src/safe-guides/coding_practice/async-await/G.ASY.01.md: -------------------------------------------------------------------------------- 1 | # G.ASY.01 在 async 块或函数中调用 async 函数或闭包请不要忘记添加.await 2 | -------------------------------------------------------------------------------- /src/safe-guides/coding_practice/cargo/G.CAR.01.md: -------------------------------------------------------------------------------- 1 | # G.CAR.01 当项目是可执行程序而非库时，建议使用 src/main.rs 和 src/lib.rs 模式 2 | -------------------------------------------------------------------------------- /src/safe-guides/coding_practice/collections/G.CLT.01.md: -------------------------------------------------------------------------------- 1 | # G.CLT.01 非必要情况下，不要使用LinkedList，而用Vec或VecDeque代替 2 | -------------------------------------------------------------------------------- /src/safe-guides/coding_practice/data-type/char/G.TYP.CHR.02.md: -------------------------------------------------------------------------------- 1 | # G.TYP.CHR.02 字符串方法中如果需要单个字符的值作为参数，宜使用字符而非字符串 2 | -------------------------------------------------------------------------------- /src/safe-guides/coding_practice/data-type/enum/G.TYP.ENM.04.md: -------------------------------------------------------------------------------- 1 | # G.TYP.ENM.04 不宜在use语句中引入Enum的全部变体（variants） 2 | -------------------------------------------------------------------------------- /src/safe-guides/coding_practice/data-type/float/G.TYP.FLT.01.md: -------------------------------------------------------------------------------- 1 | # G.TYP.FLT.01 使用浮点数字面量时，要警惕是否存在被Rust编译器截断的风险 2 | -------------------------------------------------------------------------------- /src/safe-guides/coding_practice/data-type/float/G.TYP.FLT.05.md: -------------------------------------------------------------------------------- 1 | # G.TYP.FLT.05 禁止在浮点数和整数相互转换时使用 transmute 2 | -------------------------------------------------------------------------------- /src/safe-guides/coding_practice/data-type/struct/G.TYP.SCT.02.md: -------------------------------------------------------------------------------- 1 | # G.TYP.SCT.02 当结构体中有超过三个布尔类型的字段，宜将其独立为新的枚举类 2 | -------------------------------------------------------------------------------- /src/safe-guides/coding_practice/data-type/struct/P.TYP.SCT.01.md: -------------------------------------------------------------------------------- 1 | # P.TYP.SCT.01 为结构体实现构造性方法时，避免构造后再初始化的情况 2 | -------------------------------------------------------------------------------- /src/safe-guides/coding_practice/data-type/struct/P.TYP.SCT.02.md: -------------------------------------------------------------------------------- 1 | # P.TYP.SCT.02 结构体实例需要默认实现时，宜使用Default特质 2 | -------------------------------------------------------------------------------- /src/safe-guides/coding_practice/data-type/vec/P.TYP.VEC.02.md: -------------------------------------------------------------------------------- 1 | # P.TYP.VEC.02 创建动态数组时，宜预先分配足够容量，避免后续操作中产生多次分配 2 | -------------------------------------------------------------------------------- /src/safe-guides/coding_practice/generic/G.GEN.02.md: -------------------------------------------------------------------------------- 1 | # G.GEN.02 使用 Rust 标准库中某些方法，要注意避免使用其泛型默认实现，而应该使用具体类型的实现 2 | -------------------------------------------------------------------------------- /src/safe-guides/coding_practice/io/P.FIO.01.md: -------------------------------------------------------------------------------- 1 | # P.FIO.01 使用 read_to_end/read_to_string方法时注意文件的大小能否一次性读入内存中 2 | -------------------------------------------------------------------------------- /src/safe-guides/coding_practice/memory/box/G.MEM.BOX.02.md: -------------------------------------------------------------------------------- 1 | # G.MEM.BOX.02 一般情况下，不应直接对已经在堆上分配内存的类型进行 Box 装箱 2 | -------------------------------------------------------------------------------- /src/safe-guides/coding_practice/traits/std-builtin/G.TRA.BLN.09.md: -------------------------------------------------------------------------------- 1 | # G.TRA.BLN.09 一般情况下不要给 Copy 类型手工实现 Clone 2 | -------------------------------------------------------------------------------- /src/safe-guides/coding_practice/traits/trait-object/P.TRA.OBJ.01.md: -------------------------------------------------------------------------------- 1 | # P.TRA.OBJ.01 根据场景合理选择使用trait对象或泛型静态分发 2 | -------------------------------------------------------------------------------- /src/safe-guides/coding_practice/unsafe_rust/ffi/P.UNS.FFI.01.md: -------------------------------------------------------------------------------- 1 | # P.UNS.FFI.01 避免从公开的 Rust API 直接传字符串到 C 中 2 | -------------------------------------------------------------------------------- /src/safe-guides/coding_practice/unsafe_rust/ffi/P.UNS.FFI.04.md: -------------------------------------------------------------------------------- 1 | # P.UNS.FFI.04 如果一个函数正在跨越 FFi 边界，那么需要处理 Panic 2 | -------------------------------------------------------------------------------- /src/safe-guides/coding_practice/unsafe_rust/mem/G.UNS.MEM.01.md: -------------------------------------------------------------------------------- 1 | # G.UNS.MEM.01 使用 MaybeUninit 来处理未初始化的内存 2 | -------------------------------------------------------------------------------- /src/safe-guides/coding_practice/unsafe_rust/raw_ptr/P.UNS.PTR.02.md: -------------------------------------------------------------------------------- 1 | # P.UNS.PTR.02 建议使用 NonNull 来替代 *mut T 2 | -------------------------------------------------------------------------------- /src/safe-guides/coding_practice/unsafe_rust/safe_abstract/P.UNS.SAS.06.md: -------------------------------------------------------------------------------- 1 | # P.UNS.SAS.06 不要随便在公开的 API 中暴露裸指针 2 | -------------------------------------------------------------------------------- /src/safe-guides/code_style/naming/P.NAM.03.md: -------------------------------------------------------------------------------- 1 | # P.NAM.03 Identifier naming should be in line with reading habits 2 | -------------------------------------------------------------------------------- /src/safe-guides/code_style/naming/P.NAM.08.md: -------------------------------------------------------------------------------- 1 | # P.NAM.08 Avoid adding type identifiers to the naming of variables 2 | -------------------------------------------------------------------------------- /src/safe-guides/coding_practice/collections/P.CLT.01.md: -------------------------------------------------------------------------------- 1 | # P.CLT.01 创建HashMap、VecDeque时，可以预先分配大约足够的容量来避免后续操作中产生多次分配 2 | -------------------------------------------------------------------------------- /src/safe-guides/coding_practice/control-flow/G.CTF.01.md: -------------------------------------------------------------------------------- 1 | # G.CTF.01 当需要通过多个if判断来比较大小来区分不同情况时，优先使用match和cmp来代替if表达式 2 | -------------------------------------------------------------------------------- /src/safe-guides/coding_practice/data-type/bool/G.TYP.BOL.02.md: -------------------------------------------------------------------------------- 1 | # G.TYP.BOL.02 如果 match 匹配表达式为布尔类型，宜使用 if 表达式来代替 2 | -------------------------------------------------------------------------------- /src/safe-guides/coding_practice/data-type/char/G.TYP.CHR.03.md: -------------------------------------------------------------------------------- 1 | # G.TYP.CHR.03 需要将整数转换为字符时，应使用安全转换函数，而非 transmute 2 | -------------------------------------------------------------------------------- /src/safe-guides/coding_practice/data-type/enum/G.TYP.ENM.05.md: -------------------------------------------------------------------------------- 1 | # G.TYP.ENM.05 对外导出的公开Enum，宜添加#[non_exhaustive]属性 2 | -------------------------------------------------------------------------------- /src/safe-guides/coding_practice/data-type/float/G.TYP.FLT.03.md: -------------------------------------------------------------------------------- 1 | # G.TYP.FLT.03 对精度高要求的场景下，使用浮点数进行运算和比较时需要注意精度损失 2 | -------------------------------------------------------------------------------- /src/safe-guides/coding_practice/error-handle/G.ERR.01.md: -------------------------------------------------------------------------------- 1 | # G.ERR.01 在处理 Option 和 Result 类型时，不要随便使用 unwrap 2 | -------------------------------------------------------------------------------- /src/safe-guides/coding_practice/macros/decl/P.MAC.DCL.05.md: -------------------------------------------------------------------------------- 1 | # P.MAC.DCL.05 使用宏替换（substitution）元变量的时候要注意选择合适的片段分类符 2 | -------------------------------------------------------------------------------- /src/safe-guides/coding_practice/threads/lock/G.MTH.LCK.02.md: -------------------------------------------------------------------------------- 1 | # G.MTH.LCK.02 宜使用 Arc / Arc<[T]> 来代替 Arc / Arc 2 | -------------------------------------------------------------------------------- /src/safe-guides/coding_practice/unsafe_rust/ffi/P.UNS.FFI.02.md: -------------------------------------------------------------------------------- 1 | # P.UNS.FFI.02 在使用标准库 std::ffi 模块提供的类型时需要仔细查看其文档 2 | -------------------------------------------------------------------------------- /src/safe-guides/coding_practice/unsafe_rust/ffi/P.UNS.FFI.10.md: -------------------------------------------------------------------------------- 1 | # P.UNS.FFI.10 当 Rust 函数导出外部函数时，必须从设计上保证被跨线程调用的安全性 2 | -------------------------------------------------------------------------------- /src/safe-guides/coding_practice/unsafe_rust/mem/P.UNS.MEM.04.md: -------------------------------------------------------------------------------- 1 | # P.UNS.MEM.04 尽量用可重入(reentrant)版本的 C-API 或系统调用 2 | -------------------------------------------------------------------------------- /src/safe-guides/coding_practice/unsafe_rust/safe_abstract/P.UNS.SAS.03.md: -------------------------------------------------------------------------------- 1 | # P.UNS.SAS.03 不要随便在公开的 API 中暴露未初始化内存 2 | -------------------------------------------------------------------------------- /src/safe-guides/coding_practice/unsafe_rust/safe_abstract/P.UNS.SAS.04.md: -------------------------------------------------------------------------------- 1 | # P.UNS.SAS.04 避免因为 Panic Safety 而导致双重释放 2 | -------------------------------------------------------------------------------- /src/safe-guides/coding_practice/unsafe_rust/safe_abstract/P.UNS.SAS.08.md: -------------------------------------------------------------------------------- 1 | # P.UNS.SAS.08 函数参数是不可变借用的时候，返回值不应该是可变借用 2 | -------------------------------------------------------------------------------- /src/safe-guides/coding_practice/data-type/array/G.TYP.ARR.03.md: -------------------------------------------------------------------------------- 1 | # G.TYP.ARR.03 当数组元素为原生数据类型（Primitive），排序时优先选用非稳定排序 2 | -------------------------------------------------------------------------------- /src/safe-guides/coding_practice/data-type/bool/G.TYP.BOL.05.md: -------------------------------------------------------------------------------- 1 | # G.TYP.BOL.05 非必要时，布尔运算应使用逻辑运算符( &&/||)而非位运算符 (&/|) 2 | -------------------------------------------------------------------------------- /src/safe-guides/coding_practice/data-type/struct/G.TYP.SCT.01.md: -------------------------------------------------------------------------------- 1 | # G.TYP.SCT.01 对外导出的公开的 Struct，宜添加#[non_exhaustive]属性 2 | -------------------------------------------------------------------------------- /src/safe-guides/coding_practice/generic/P.GEN.05.md: -------------------------------------------------------------------------------- 1 | # P.GEN.05 定义泛型函数时，如果该函数实现用到来自 trait 定义的相关行为，需要为泛型指定相关 trait 的限定 2 | -------------------------------------------------------------------------------- /src/safe-guides/coding_practice/statics/G.STV.01.md: -------------------------------------------------------------------------------- 1 | # G.STV.01 Shouldn't use `static mut` as global variable directly 2 | -------------------------------------------------------------------------------- /src/safe-guides/coding_practice/strings/G.STR.03.md: -------------------------------------------------------------------------------- 1 | # G.STR.03 将只包含 ASCII字符的字符串字面量转为字节序列可以直接使用b"str" 语法代替调用as_bytes方法 2 | -------------------------------------------------------------------------------- /src/safe-guides/coding_practice/traits/std-builtin/G.TRA.BLN.03.md: -------------------------------------------------------------------------------- 1 | # G.TRA.BLN.03 能使用派生宏（Derive）自动实现Default特质就不要用手工实现 2 | -------------------------------------------------------------------------------- /src/safe-guides/coding_practice/unsafe_rust/ffi/P.UNS.FFI.09.md: -------------------------------------------------------------------------------- 1 | # P.UNS.FFI.09 当 Rust 调用外部 C 函数时，如果可以确认安全，可以通过引用来代替裸指针 2 | -------------------------------------------------------------------------------- /src/safe-guides/coding_practice/unsafe_rust/mem/P.UNS.MEM.03.md: -------------------------------------------------------------------------------- 1 | # P.UNS.MEM.03 不能让 String/Vec 自动 Drop 其它进程或动态库的内存数据 2 | -------------------------------------------------------------------------------- /src/safe-guides/coding_practice/unsafe_rust/raw_ptr/G.UNS.PTR.01.md: -------------------------------------------------------------------------------- 1 | # G.UNS.PTR.01 当指针类型被强转为和当前内存对齐不一致的指针类型时，禁止对其解引用 2 | -------------------------------------------------------------------------------- /src/safe-guides/coding_practice/unsafe_rust/raw_ptr/G.UNS.PTR.03.md: -------------------------------------------------------------------------------- 1 | # G.UNS.PTR.03 尽量使用 pointer::cast 来代替 使用 as 强转指针 2 | -------------------------------------------------------------------------------- /src/safe-guides/coding_practice/unsafe_rust/safe_abstract/P.UNS.SAS.01.md: -------------------------------------------------------------------------------- 1 | # P.UNS.SAS.01 代码中要注意是否会因为 Panic 发生而导致内存安全问题 2 | -------------------------------------------------------------------------------- /src/safe-guides/coding_practice/unsafe_rust/safe_abstract/P.UNS.SAS.02.md: -------------------------------------------------------------------------------- 1 | # P.UNS.SAS.02 Unsafe 代码编写者有义务检查代码是否满足安全不变式 2 | -------------------------------------------------------------------------------- /src/safe-guides/coding_practice/unsafe_rust/safe_abstract/P.UNS.SAS.05.md: -------------------------------------------------------------------------------- 1 | # P.UNS.SAS.05 手动实现 auto trait 时要充分考虑其安全性 2 | -------------------------------------------------------------------------------- /src/safe-guides/coding_practice/unsafe_rust/safe_abstract/P.UNS.SAS.09.md: -------------------------------------------------------------------------------- 1 | # P.UNS.SAS.09 在任何 Unsafe 块之前都应该加 SAFETY 注释 2 | -------------------------------------------------------------------------------- /src/safe-guides/code_style/fmt/P.FMT.07.md: -------------------------------------------------------------------------------- 1 | # P.FMT.07 Both enumeration variants and structure fields should be left aligned 2 | -------------------------------------------------------------------------------- /src/safe-guides/code_style/naming/G.NAM.02.md: -------------------------------------------------------------------------------- 1 | # G.NAM.02 Type conversion function naming needs to follow ownership semantics 2 | -------------------------------------------------------------------------------- /src/safe-guides/coding_practice/threads/lock/G.MTH.LCK.03.md: -------------------------------------------------------------------------------- 1 | # G.MTH.LCK.03 尽量避免直接使用标准库 std::sync 模块中的同步原语，替换为 parking_lot 2 | -------------------------------------------------------------------------------- /src/safe-guides/coding_practice/traits/std-builtin/G.TRA.BLN.04.md: -------------------------------------------------------------------------------- 1 | # G.TRA.BLN.04 在使用#[derive(Hash)] 的时候，避免再手工实现 PartialEq 2 | -------------------------------------------------------------------------------- /src/safe-guides/coding_practice/traits/std-builtin/G.TRA.BLN.05.md: -------------------------------------------------------------------------------- 1 | # G.TRA.BLN.05 在使用#[derive(Ord)] 的时候，避免再手工实现 PartialOrd 2 | -------------------------------------------------------------------------------- /src/safe-guides/coding_practice/unsafe_rust/ffi/P.UNS.FFI.05.md: -------------------------------------------------------------------------------- 1 | # P.UNS.FFI.05 建议使用诸如标准库或 libc crate 所提供的可移植类型别名，而不是特定平台的类型 2 | -------------------------------------------------------------------------------- /src/safe-guides/coding_practice/unsafe_rust/safe_abstract/G.UNS.SAS.01.md: -------------------------------------------------------------------------------- 1 | # G.UNS.SAS.01 在公开的 unsafe 函数的文档中必须增加 Safety 注释 2 | -------------------------------------------------------------------------------- /src/safe-guides/coding_practice/unsafe_rust/safe_abstract/P.UNS.SAS.07.md: -------------------------------------------------------------------------------- 1 | # P.UNS.SAS.07 在抽象安全方法的同时，也建议为性能考虑而增加相应的 Unsafe 方法 2 | -------------------------------------------------------------------------------- /src/safe-guides/code_style/naming/P.NAM.02.md: -------------------------------------------------------------------------------- 1 | # P.NAM.02 Names for cargo features should not contain meaningless placeholders 2 | -------------------------------------------------------------------------------- /src/safe-guides/coding_practice/consts/G.CNS.04.md: -------------------------------------------------------------------------------- 1 | # G.CNS.04 Shouldn't add explicit `'static` lifetime in constant declaration 2 | -------------------------------------------------------------------------------- /src/safe-guides/coding_practice/memory/smart-ptr/P.MEM.SPT.01.md: -------------------------------------------------------------------------------- 1 | # P.MEM.SPT.01 使用 RefCell 时宜使用 try_borrow/try_borrow_mut 方法 2 | -------------------------------------------------------------------------------- /src/safe-guides/coding_practice/traits/std-builtin/G.TRA.BLN.01.md: -------------------------------------------------------------------------------- 1 | # G.TRA.BLN.01 应该具体类型的 default() 方法代替 Default::default() 调用 2 | -------------------------------------------------------------------------------- /src/safe-guides/coding_practice/unsafe_rust/ffi/P.UNS.FFI.06.md: -------------------------------------------------------------------------------- 1 | # P.UNS.FFI.06 Rust 和 C 之间传递字符或字符串时需要注意字符串要符合 C-ABI 以及 字符串的编码 2 | -------------------------------------------------------------------------------- /src/safe-guides/coding_practice/unsafe_rust/ffi/P.UNS.FFI.11.md: -------------------------------------------------------------------------------- 1 | # P.UNS.FFI.11 如需引用指定为 #[repr(packed)] 内存布局的结构体成员字段要注意合理规避未定义行为 2 | -------------------------------------------------------------------------------- /src/safe-guides/coding_practice/unsafe_rust/ffi/P.UNS.FFI.12.md: -------------------------------------------------------------------------------- 1 | # P.UNS.FFI.12 当依赖 C 端传入参数时，需要在文档注释中不变性声明，根据不同的调用场景选择合适的安全抽象方式 2 | -------------------------------------------------------------------------------- /src/safe-guides/code_style/fmt/P.FMT.04.md: -------------------------------------------------------------------------------- 1 | # P.FMT.04 Language items should be defined with the left braces position on the same line -------------------------------------------------------------------------------- /src/safe-guides/code_style/fmt/P.FMT.05.md: -------------------------------------------------------------------------------- 1 | # P.FMT.05 Block indentation should be maintained when multiple identifiers are present 2 | -------------------------------------------------------------------------------- /src/safe-guides/code_style/naming/P.NAM.06.md: -------------------------------------------------------------------------------- 1 | # P.NAM.06 Follow the `iter/ iter_mut/ into_iter` specification to generate iterators 2 | -------------------------------------------------------------------------------- /src/safe-guides/coding_practice/data-type/enum/G.TYP.ENM.03.md: -------------------------------------------------------------------------------- 1 | # G.TYP.ENM.03 在使用类似 C 语言的枚举写法且使用repr(isize/usize) 布局时注意 32位架构上截断的问题 2 | -------------------------------------------------------------------------------- /src/safe-guides/coding_practice/threads/lock/G.MTH.LCK.04.md: -------------------------------------------------------------------------------- 1 | # G.MTH.LCK.04 尽量避免直接使用标准库 std::sync::mpsc 模块中的 channel，替换为 crossbeam 2 | -------------------------------------------------------------------------------- /src/safe-guides/coding_practice/traits/std-builtin/G.TRA.BLN.06.md: -------------------------------------------------------------------------------- 1 | # G.TRA.BLN.06 不要对实现 Copy 或引用类型调用 std::mem::drop 和 std::mem::forgot 2 | -------------------------------------------------------------------------------- /src/safe-guides/coding_practice/unsafe_rust/ffi/P.UNS.FFI.03.md: -------------------------------------------------------------------------------- 1 | # P.UNS.FFI.03 当使用来自 C 的指针时，如果该指针需要管理内存，则需要为包装该指针的 Rust 类型实现 Drop 特质 2 | -------------------------------------------------------------------------------- /src/safe-guides/coding_practice/unsafe_rust/raw_ptr/P.UNS.PTR.03.md: -------------------------------------------------------------------------------- 1 | # P.UNS.PTR.03 使用指针类型构造泛型结构体时，需要使用 PhantomData 来指定 T上的协变和所有权 2 | -------------------------------------------------------------------------------- /src/safe-guides/coding_practice/error-handle/P.ERR.02.md: -------------------------------------------------------------------------------- 1 | # P.ERR.02 在确定 Option 和 Result类型的值不可能是 None 或 Err 时，请用 expect 代替 unwrap() 2 | -------------------------------------------------------------------------------- /src/safe-guides/coding_practice/traits/std-builtin/G.TRA.BLN.07.md: -------------------------------------------------------------------------------- 1 | # G.TRA.BLN.07 对实现 Copy 的可迭代类型来说，要通过迭代器拷贝其所有元素时，应该使用 copied方法，而非cloned 2 | -------------------------------------------------------------------------------- /src/safe-guides/coding_practice/unsafe_rust/safe_abstract/G.UNS.SAS.02.md: -------------------------------------------------------------------------------- 1 | # G.UNS.SAS.02 在 Unafe 函数中应使用 assert! 而非 debug_assert! 去校验边界条件 2 | -------------------------------------------------------------------------------- /src/safe-guides/code_style/naming/P.NAM.04.md: -------------------------------------------------------------------------------- 1 | # P.NAM.04 The larger the scope, the more precise the naming, and the opposite should be short 2 | -------------------------------------------------------------------------------- /src/safe-guides/code_style/naming/P.NAM.09.md: -------------------------------------------------------------------------------- 1 | # P.NAM.09 Global static variables should be defined with the prefix `G_` to distinguish them from constants 2 | -------------------------------------------------------------------------------- /src/safe-guides/code_style/naming/P.NAM.07.md: -------------------------------------------------------------------------------- 1 | # P.NAM.07 Avoid using special names such as language built-in reserved words, keywords, built-in types and traits -------------------------------------------------------------------------------- /src/safe-guides/code_style/fmt/P.FMT.06.md: -------------------------------------------------------------------------------- 1 | # P.FMT.06 When there is a multi-line expression operation, the operator should be placed at the beginning of the line 2 | -------------------------------------------------------------------------------- /src/safe-guides/code_style/fmt/P.FMT.08.md: -------------------------------------------------------------------------------- 1 | # P.FMT.08 Line feeds for functions with more than five parameters or imported modules with more than four parameters 2 | -------------------------------------------------------------------------------- /src/safe-guides/code_style/naming.md: -------------------------------------------------------------------------------- 1 | # 2.1 Naming 2 | 3 | A good naming style allows us to quickly understand what a name represents (type, variable, function, constant, macro, etc.) and even highlights its semantics in the overall code context. Naming management is quite important to improve the readability and maintainability of your code. -------------------------------------------------------------------------------- /book.toml: -------------------------------------------------------------------------------- 1 | [book] 2 | authors = ["blackanger"] 3 | language = "en" 4 | multilingual = false 5 | src = "src" 6 | title = "Rust Coding Specification V1.0 beta" 7 | 8 | [build] 9 | create-missing = true 10 | 11 | [preprocessor.toc] 12 | command = "mdbook-toc" 13 | renderer = ["html"] 14 | max-level = 2 15 | 16 | [output.html] 17 | git-repository-url = "https://github.com/Rust-Coding-Guidelines/rust-coding-guidelines" 18 | 19 | [output.html.fold] 20 | enable = true 21 | level = 0 -------------------------------------------------------------------------------- /src/safe-guides/coding_practice/fn-design/P.FUD.02.md: -------------------------------------------------------------------------------- 1 | # P.FUD.02 Don't Use `return` for return value 2 | 3 | **[Description]** 4 | 5 | In such that function would automatically return the value of last expression in Rust, it is not required to use `return` explicitly. 6 | 7 | Only when it is necessary to return a value in procedure of function, should use `return` explicitly. 8 | 9 | **[Bad Case]** 10 | 11 | ```rust 12 | fn foo(x: usize) -> usize { 13 | if x < 42 { 14 | return x; 15 | } 16 | return x + 1; // Not Good 17 | } 18 | ``` 19 | 20 | **[Good Case]** 21 | 22 | ```rust 23 | fn foo(x: usize) -> usize { 24 | if x < 42 { 25 | return x; 26 | } 27 | x + 1 // Good 28 | } 29 | ``` 30 | 31 | 32 | -------------------------------------------------------------------------------- /src/safe-guides/code_style/comments.md: -------------------------------------------------------------------------------- 1 | # 2.3 Annotations and Documentation 2 | 3 | In Rust, there are two types of annotations: normal annotations and documentation annotations. Normal comments use `//` or `/* ... */`, and document comments use `///`, `//! ` or `/** ... **/`. 4 | 5 | When referring to "comments" in the principles and rules, this includes both normal comments and document comments. When "documentation" is mentioned, it refers specifically to documentation comments. 6 | 7 | 8 | ## Reference 9 | 10 | 1. [RFC 505: API Annotation Conventions](https://github.com/rust-lang/rfcs/blob/master/text/0505-api-comment-conventions.md) 11 | 2. [RFC 1574: API Documentation Conventions](https://github.com/rust-lang/rfcs/blob/master/text/1574-more-api-documentation-conventions.md) 12 | 3. [Making Great Docs with Rustdoc](https://www.tangramvision.com/blog/making-great-docs-with-rustdoc) 13 | 4. [Rust Doc book](https://doc.rust-lang.org/rustdoc/what-is-rustdoc.html) 14 | -------------------------------------------------------------------------------- /src/safe-guides/code_style/comments/P.CMT.05.md: -------------------------------------------------------------------------------- 1 | # P.CMT.05 Use `FIXME` and `TODO` in comments to help with task collaboration 2 | 3 | **[Description]** 4 | 5 | Collaboration can be facilitated by turning on `FIXME` and `TODO` in the comments. 6 | 7 | Note: This entry is not suitable for use with `rustfmt` related configuration items `report_fixme` and `report_todo`, which have been removed in `rustfmt` v2.0. 8 | 9 | **[Good Case]** 10 | 11 | ```rust 12 | // Good 13 | // TODO(calebcartwright): consider enabling box_patterns feature gate 14 | fn annotation_type_for_level(level: Level) -> AnnotationType { 15 | match level { 16 | Level::Bug | Level::Fatal | Level::Error => AnnotationType::Error, 17 | Level::Warning => AnnotationType::Warning, 18 | Level::Note => AnnotationType::Note, 19 | Level::Help => AnnotationType::Help, 20 | // FIXME(#59346): Not sure how to map these two levels 21 | Level::Cancelled | Level::FailureNote => AnnotationType::Error, 22 | Level::Allow => panic!("Should not call with Allow"), 23 | } 24 | } 25 | ``` 26 | -------------------------------------------------------------------------------- /.github/workflows/main.yml: -------------------------------------------------------------------------------- 1 | name: CI 2 | 3 | on: 4 | push: 5 | branches: [ main ] 6 | pull_request: 7 | branches: [ main ] 8 | 9 | jobs: 10 | build: 11 | name: Build, Test and Deploy 12 | runs-on: ubuntu-latest 13 | steps: 14 | - uses: actions/checkout@v2 15 | - uses: actions-rs/toolchain@v1 16 | with: 17 | toolchain: stable 18 | - name: Install mdbook 19 | run: | 20 | mkdir bin 21 | curl -sSL https://github.com/rust-lang/mdBook/releases/download/v0.4.14/mdbook-v0.4.14-x86_64-unknown-linux-gnu.tar.gz | tar -xz --directory=bin 22 | echo "$(pwd)/bin" >> $GITHUB_PATH 23 | # - name: Install mdbook-toc 24 | # run: cargo install mdbook-toc 25 | # - name: Install mdbook-mermaid 26 | # run: cargo install mdbook-mermaid 27 | - run: mdbook build # In case of custom book path: mdbook build path/to/mybook && mdbook test path/to/mybook 28 | - uses: JamesIves/github-pages-deploy-action@4.1.7 29 | with: 30 | branch: gh-pages # The branch the action should deploy to. 31 | folder: book # The folder the action should deploy. -------------------------------------------------------------------------------- /LICENSE: -------------------------------------------------------------------------------- 1 | MIT License 2 | 3 | Copyright (c) 2021 Rust Coding Guidelines (Unofficial) 4 | 5 | Permission is hereby granted, free of charge, to any person obtaining a copy 6 | of this software and associated documentation files (the "Software"), to deal 7 | in the Software without restriction, including without limitation the rights 8 | to use, copy, modify, merge, publish, distribute, sublicense, and/or sell 9 | copies of the Software, and to permit persons to whom the Software is 10 | furnished to do so, subject to the following conditions: 11 | 12 | The above copyright notice and this permission notice shall be included in all 13 | copies or substantial portions of the Software. 14 | 15 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 16 | IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 17 | FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE 18 | AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 19 | LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, 20 | OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE 21 | SOFTWARE. 22 | -------------------------------------------------------------------------------- /src/safe-guides/coding_practice/fn-design/P.FUD.01.md: -------------------------------------------------------------------------------- 1 | # P.FUD.01 Should rebind variables which pass into closure 2 | 3 | **[Description]** 4 | 5 | By default, closure captures environment variables with `borrow`, or it is also allowed to pass environment variables into closure with `move` keyword. 6 | 7 | It is more readable to rebind and regroup these variables which pass into closure. 8 | 9 | **[Bad Case]** 10 | 11 | ```rust 12 | use std::rc::Rc; 13 | let num1 = Rc::new(1); 14 | let num2 = Rc::new(2); 15 | let num3 = Rc::new(3); 16 | let closure = { 17 | // ownership of `num1` has been moved 18 | let num2 = num2.clone(); 19 | let num3 = num3.as_ref(); 20 | move || { 21 | *num1 + *num2+ *num3; // Not Good. 22 | } 23 | }; 24 | ``` 25 | 26 | 27 | **[Good Case]** 28 | 29 | ```rust 30 | use std::rc::Rc; 31 | 32 | let num1 = Rc::new(1); 33 | let num2 = Rc::new(2); 34 | let num3 = Rc::new(3); 35 | 36 | // Good: rebind variables seperately, which would pass into closure. 37 | let num2_cloned = num2.clone(); 38 | let num3_borrowed = num3.as_ref(); 39 | let closure = move || { 40 | *num1 + *num2_cloned + *num3_borrowed; // Good. 41 | }; 42 | ``` 43 | 44 | 45 | 46 | -------------------------------------------------------------------------------- /src/safe-guides/coding_practice/fn-design/G.FUD.05.md: -------------------------------------------------------------------------------- 1 | # G.FUD.05 Don't always specify `#[inline(always)]` for function 2 | 3 | **[Level] Advice** 4 | 5 | **[Description]** 6 | 7 | `inline` could imporve performance, but also increase compilation time and size. You have to make a tradeoff among Performance, Compilation time and Compilation size in Rust, and it is recommended to use `inline` on demand. 8 | 9 | 10 | **[Bad Case]** 11 | 12 | ```rust 13 | #![warn(clippy::inline_always)] 14 | 15 | // Not Good 16 | #[inline(always)] 17 | fn not_quite_hot_code(..) { ... } 18 | ``` 19 | 20 | **[Exception]** 21 | 22 | Use `inline` on demand. i.e. it is obvious that one function is called frequently, and you could use `inline` for it to improve performance. 23 | 24 | ```rust 25 | // Good: that function is often called for recycle buffer memory, so use `inline` maximize its performance. 26 | pub fn buf_recycle(buf_id: usize) { 27 | // ... 28 | } 29 | ``` 30 | 31 | **[Lint Check]** 32 | 33 | | lint name | Clippy check | Rustc check | Lint Group | Level | 34 | | --------- | ------------ | ----------- | ---------- | ----- | 35 | | [inline_always](https://rust-lang.github.io/rust-clippy/master/#inline_always) | yes | no | pedanic | allow | 36 | 37 | -------------------------------------------------------------------------------- /src/safe-guides/coding_practice/fn-design/G.FUD.02.md: -------------------------------------------------------------------------------- 1 | # G.FUD.02 Should input as reference if parameter derives `Copy` and its value inputed by-value is a big number 2 | 3 | **[Level] Advice** 4 | 5 | **[Description]** 6 | 7 | By-value inputed parameters may emerge unnecessary `memcpy`, which could kill performance. 8 | 9 | **[Bad Case]** 10 | 11 | ```rust 12 | #![warn(clippy::large_types_passed_by_value)] 13 | 14 | #[derive(Clone, Copy)] 15 | struct TooLarge([u8; 2048]); 16 | 17 | // Not Good 18 | fn foo(v: TooLarge) {} 19 | ``` 20 | 21 | **[Good Case]** 22 | 23 | ```rust 24 | #![warn(clippy::large_types_passed_by_value)] 25 | 26 | #[derive(Clone, Copy)] 27 | struct TooLarge([u8; 2048]); 28 | 29 | // Good 30 | fn foo(v: &TooLarge) {} 31 | ``` 32 | 33 | **[Lint Check]** 34 | 35 | | lint name | Clippy check | Rustc check | Lint Group | Level | 36 | | --------- | ------------ | ----------- | ---------- | ----- | 37 | | [large_types_passed_by_value](https://rust-lang.github.io/rust-clippy/master/#large_types_passed_by_value) | yes | no | pedanic | allow | 38 | 39 | This lint corresponds to the following configuration of `clippy.toml` 40 | 41 | ```toml 42 | # if function is an exported api, then the lint would not be triggered, which aims to prevent devastated change for api. the default is true. 43 | avoid-breaking-exported-api=true 44 | ``` 45 | -------------------------------------------------------------------------------- /src/safe-guides/coding_practice/fn-design/G.FUD.03.md: -------------------------------------------------------------------------------- 1 | # G.FUD.03 Should refactor into customized `struct` or `enum` if there are too many `bool` type's function parameters 2 | 3 | **[Level] Advice** 4 | 5 | **[Description]** 6 | 7 | Too many `bool` parameters is bad for memory and prone to issue errors. As to use typeinference and borrowchecker effectively, we should refactor into cutomized `struct` and `enum` in this case. 8 | 9 | **[Bad Case]** 10 | 11 | ```rust 12 | #![warn(clippy::fn_params_excessive_bools)] 13 | 14 | // Not Good 15 | fn f(is_rould: bool, is_hot: bool) { ... } 16 | ``` 17 | 18 | **[Good Case]** 19 | 20 | ```rust 21 | #![warn(clippy::fn_params_excessive_bools)] 22 | 23 | enum Shap { 24 | Round, 25 | Spiky, 26 | } 27 | 28 | enum Temperature { 29 | Hot, 30 | IceCold, 31 | } 32 | 33 | // Good 34 | fn f(shape: Shape, temperature: Temperature) { ... } 35 | ``` 36 | 37 | **[Lint Check]** 38 | 39 | | lint name | Clippy check | Rustc check | Lint Group | Level | 40 | | --------- | ------------ | ----------- | ---------- | ----- | 41 | | [fn_params_excessive_bools](https://rust-lang.github.io/rust-clippy/master/#fn_params_excessive_bools) | yes | no | pedanic | allow | 42 | 43 | This lint corresponds to the following configuration of `clippy.toml` 44 | 45 | ```toml 46 | # In order to limit maximum number of bool type's parameters, the default is 3. 47 | max-fn-params-bools=3 48 | ``` 49 | -------------------------------------------------------------------------------- /src/safe-guides/coding_practice/fn-design/G.FUD.01.md: -------------------------------------------------------------------------------- 1 | # G.FUD.01 Less than 5 function parameters 2 | 3 | **[Level] Advice** 4 | 5 | **[Description]** 6 | 7 | In order to improve readability of code, it's better to set less than 5 function's parameters. 8 | 9 | 10 | **[Bad Case]** 11 | 12 | ```rust 13 | struct Color; 14 | // Not Good 15 | fn foo(x: f32, y: f32, name: &str, c: Color, w: u32, h: u32, a: u32, b: u32) { 16 | // .. 17 | } 18 | ``` 19 | 20 | **[Good Case]** 21 | 22 | Refine function's parameters as possible. 23 | 24 | ```rust 25 | struct Color; 26 | // Good: use const generic here to receive multiple u32 typed parameters afterward. 27 | // use tuple to refine 2~3 parameters as one. 28 | fn foo(x: (f32, f32), name: &str, c: Color, last: [T;N]) { 29 | ; 30 | } 31 | 32 | fn main() { 33 | let arr = [1u32, 2u32]; 34 | foo((1.0f32, 2.0f32), "hello", Color, arr); 35 | let arr = [1.0f32, 2.0f32, 3.0f32]; 36 | foo((1.0f32, 2.0f32), "hello", Color, arr); 37 | } 38 | ``` 39 | 40 | **[Lint Check]** 41 | 42 | | lint name | Clippy check | Rustc Check | Lint Group | level | 43 | | --------- | ------------ | ----------- | ---------- | ----- | 44 | | [too_many_arguments](https://rust-lang.github.io/rust-clippy/master/#too_many_arguments) | yes | no | complexity | warn | 45 | 46 | This lint corresponds to the following configuration of `clippy.toml`: 47 | 48 | ```toml 49 | # less than 5 parameters 50 | too-many-arguments-threshold=5 51 | ``` 52 | -------------------------------------------------------------------------------- /src/safe-guides/code_style/fmt.md: -------------------------------------------------------------------------------- 1 | # 2.2 Format 2 | 3 | A uniform coding style is developed to improve the readability of code and make it easier to maintain daily code and review code between teams. 4 | 5 | Rust has an automated formatting tool, rustfmt, to help developers get rid of the manual work of formatting code and improve productivity. However, what style specification rustfmt follows, as developers need to understand, when writing code can be proactively written in such a style. 6 | 7 | **Description**: 8 | 9 | For unstable configuration items in `rustfmt` (`Stable` is `No`), it means that the configuration item cannot be changed in the stable (Stable) version of Rust, but its default value will take effect when `cargo fmt`. Under Nightly Rust, all configurations can be customized. 10 | 11 | For information on how to use unstable configuration items in Stable Rust, sample configurations, and other global configuration item descriptions, see: [Rustfmt Configuration Description](./../Appendix/tools/rustfmt.md). 12 | 13 | **Caution** 14 | 15 | Because the rustfmt tool automatically modifies code, to ensure that rustfmt does not accidentally change the wrong code, you should pay attention to the following two descriptions when using rustfmt: 1. 16 | 17 | 1. Always make sure that the rustfmt command is executed after all the code has been modified and compiled. Because the code is not compiled during rustfmt execution, there is no static check protection. 2. 18 | 19 | 2. If you are using an IDE or editor with automatic protection turned on, do not turn on automatic rustfmt execution. 20 | -------------------------------------------------------------------------------- /src/safe-guides/code_style/comments/G.CMT.01.md: -------------------------------------------------------------------------------- 1 | # G.CMT.01 Error comments need to added the documentation of functions that return `Result` types in the public 2 | 3 | **[Level]** Suggestion 4 | 5 | **[Description]** 6 | 7 | In the public (pub) documentation of functions that return `Result` types, it is recommended to add `# Error` comments to explain what scenarios the function will return what kind of error type, so that users can easily handle errors. 8 | 9 | Description: This rule can be detected by cargo clippy, but it does not warn by default. 10 | 11 | **[Bad Case]** 12 | 13 | ```rust 14 | #![warn(clippy::missing_errors_doc)] 15 | 16 | use std::io; 17 | // Bad： Clippy will be warned "warning: docs for function returning `Result` missing `# Errors` section" 18 | pub fn read(filename: String) -> io::Result { 19 | unimplemented!(); 20 | } 21 | ``` 22 | 23 | **[Good Case]** 24 | 25 | ```rust 26 | #![warn(clippy::missing_errors_doc)] 27 | 28 | use std::io; 29 | // Good：adding normatives Errors documentation comments 30 | 31 | /// # Errors 32 | /// 33 | /// Will return `Err` if `filename` does not exist or the user does not have 34 | /// permission to read it. 35 | pub fn read(filename: String) -> io::Result { 36 | unimplemented!(); 37 | } 38 | ``` 39 | 40 | **[Lint detection]** 41 | 42 | | Lint name | Clippy detectable | Rustc detectable | Lint Group | Default level | 43 | | ---------------------------------------------------------------------------------------------------- | ----------------- | ---------------- | ---------- | ------------- | 44 | | [missing_errors_doc ](https://rust-lang.github.io/rust-clippy/master/index.html#missing_errors_doc ) | yes | no | Style | allow | -------------------------------------------------------------------------------- /src/safe-guides/code_style/comments/G.CMT.03.md: -------------------------------------------------------------------------------- 1 | # G.CMT.03 Use spaces in document comments instead of tabs 2 | 3 | **[Level]** Suggestion 4 | 5 | **[Description]** 6 | 7 | Rust code style promotes the use of **four spaces** instead of tabs, and **four spaces** should be used consistently in the documentation comments. 8 | 9 | **[Bad Case]** 10 | 11 | Tab is used in the following document comments. 12 | 13 | ```rust 14 | // Bad：Tab indentation is used in document comments 15 | /// 16 | /// Struct to hold two strings: 17 | /// - first one 18 | /// - second one 19 | pub struct DoubleString { 20 | /// 21 | /// - First String: 22 | /// - needs to be inside here 23 | first_string: String, 24 | /// 25 | /// - Second String: 26 | /// - needs to be inside here 27 | second_string: String, 28 | } 29 | ``` 30 | 31 | **[Good Case]** 32 | 33 | ```rust 34 | // Good：Four spaces indentation is used in document comments 35 | /// 36 | /// Struct to hold two strings: 37 | /// - first one 38 | /// - second one 39 | pub struct DoubleString { 40 | /// 41 | /// - First String: 42 | /// - needs to be inside here 43 | first_string: String, 44 | /// 45 | /// - Second String: 46 | /// - needs to be inside here 47 | second_string: String, 48 | } 49 | ``` 50 | 51 | **[Lint detect]** 52 | 53 | | Lint name | Clippy detectable | Rustc detectable | Lint Group | Default level | 54 | | -------------------------------------------------------------------------------------------------------- | ----------------- | ---------------- | ---------- | ------------- | 55 | | [tabs_in_doc_comments ](https://rust-lang.github.io/rust-clippy/master/index.html#tabs_in_doc_comments ) | yes | no | Style | warn | 56 | s -------------------------------------------------------------------------------- /src/safe-guides/code_style/comments/G.CMT.02.md: -------------------------------------------------------------------------------- 1 | # G.CMT.02 If a Panic occurs under certain circumstances in the public API, add a Panic comment to the corresponding document 2 | 3 | **[Level]** Requirements 4 | 5 | **[Description]** 6 | 7 | In the public (pub) function documentation, it is recommended to add `# Panic` comments to explain under what conditions the function will Panic, so that users can pre-process it. 8 | 9 | Description: This rule is detected by cargo clippy. It does not warn by default. 10 | 11 | **[Bad Case]** 12 | 13 | ```rust 14 | #![warn(clippy::missing_panics_doc)] 15 | 16 | // Bad：If do not add Panic relevant comments.`Clippy` will raise error: "warning: docs for function which may panic missing `# Panics` section"。 17 | pub fn divide_by(x: i32, y: i32) -> i32 { 18 | if y == 0 { 19 | panic!("Cannot divide by 0") 20 | } else { 21 | x / y 22 | } 23 | } 24 | ``` 25 | 26 | **[Good Case]** 27 | 28 | ```rust 29 | #![warn(clippy::missing_panics_doc)] 30 | 31 | // Good：Added Panic comments 32 | /// # Panics 33 | /// 34 | /// Will panic if y is 0 35 | pub fn divide_by(x: i32, y: i32) -> i32 { 36 | if y == 0 { 37 | panic!("Cannot divide by 0") 38 | } else { 39 | x / y 40 | } 41 | } 42 | ``` 43 | 44 | **[Lint detect]** 45 | 46 | | Lint name | Clippy detectable | Rustc detectable | Lint Group | Default level | 47 | | ---------------------------------------------------------------------------------------------------- | ----------------- | ---------------- | ---------- | ------------- | 48 | | [missing_panics_doc ](https://rust-lang.github.io/rust-clippy/master/index.html#missing_panics_doc ) | yes | no | Style | allow | 49 | 50 | Default is `allow`，But this pricipal need to be set `#![warn(clippy::missing_panics_doc)]`。 -------------------------------------------------------------------------------- /src/safe-guides/code_style/naming/P.NAM.01.md: -------------------------------------------------------------------------------- 1 | # P.NAM.01 The naming convention for identifiers in the same crate should use a uniform word order 2 | 3 | **[Description]** 4 | 5 | The particular choice of word order is not important, but pay attention to consistency within the crate and consistency with similar functionality in the standard library. 6 | 7 | > For example: 8 | > 9 | > If the naming of types in crate were in **verb-object-error** word order, we need to follow the same order when we adding new types. 10 | 11 | Here are some error types from the standard library: 12 | 13 | - [`JoinPathsError`](https://doc.rust-lang.org/std/env/struct.JoinPathsError.html) 14 | - [`ParseBoolError`](https://doc.rust-lang.org/std/str/struct.ParseBoolError.html) 15 | - [`ParseCharError`](https://doc.rust-lang.org/std/char/struct.ParseCharError.html) 16 | - [`ParseFloatError`](https://doc.rust-lang.org/std/num/struct.ParseFloatError.html) 17 | - [`ParseIntError`](https://doc.rust-lang.org/std/num/struct.ParseIntError.html) 18 | - [`RecvTimeoutError`](https://doc.rust-lang.org/std/sync/mpsc/enum.RecvTimeoutError.html) 19 | - [`StripPrefixError`](https://doc.rust-lang.org/std/path/struct.StripPrefixError.html) 20 | 21 | All of these use verb-object-error word order. If we were adding an error to represent an address failing to parse, for consistency we would want to name it in verb-object-error order like `ParseAddrError` rather than `AddrParseError`. 22 | 23 | > Note: The `AddrParseError` of module `net` in the standard library is an exception. Most of the error types from the standard library follow the verb-object-error word order. 24 | 25 | **[Bad Case]** 26 | 27 | ```rust 28 | // Bad：Not the "verb-object-error" order, should be `ParseAddrError` 29 | struct AddrParseError {} 30 | ``` 31 | 32 | **[Good Case]** 33 | 34 | ```rust 35 | // Good: The order is the same as the standard library 36 | struct ParseAddrError{} 37 | ``` 38 | 39 | -------------------------------------------------------------------------------- /src/safe-guides/coding_practice/fn-design/G.FUD.06.md: -------------------------------------------------------------------------------- 1 | # G.FUD.06 Parameters Should be compatible with multiple types 2 | 3 | **[Level] Advice** 4 | 5 | **[Description]** 6 | 7 | It could enable parameters to be compatible with multiple types, which is benificial for the scalability of code. 8 | 9 | 10 | **[Bad Case]** 11 | 12 | ```rust 13 | // Not Good 14 | fn three_vowels(word: &String) -> bool { 15 | let mut vowel_count = 0; 16 | for c in word.chars() { 17 | match c { 18 | 'a' | 'e' | 'i' | 'o' | 'u' => { 19 | vowel_count += 1; 20 | if vowel_count >= 3 { 21 | return true 22 | } 23 | } 24 | _ => voweled_count = 0 25 | } 26 | } 27 | false 28 | } 29 | 30 | fn main() { 31 | let sentence_string = "Once upon a time, there was a friendly curious crab named Ferris".to_string(); 32 | for word in sentence_string.split(' ') { 33 | if three_vowels(word.to_string()) { 34 | println!("{} has three consecutive vowels!", word); 35 | } 36 | } 37 | } 38 | ``` 39 | 40 | **[Good Case]** 41 | 42 | ```rust 43 | // Good: Three types could be accepted as parameter here: &String / &str / &'static str. 44 | fn three_vowels(word: &str) -> bool { 45 | let mut vowel_count = 0; 46 | for c in word.chars() { 47 | match c { 48 | 'a' | 'e' | 'i' | 'o' | 'u' => { 49 | vowel_count += 1; 50 | if vowel_count >= 3 { 51 | return true 52 | } 53 | } 54 | _ => vowel_count = 0 55 | } 56 | } 57 | false 58 | } 59 | 60 | fn main() { 61 | let sentence_string = 62 | "Once upon a time, there was a friendly curious crab named Ferris".to_string(); 63 | for word in sentence_string.split(' ') { 64 | if three_vowels(word) { 65 | println!("{} has three consecutive vowels!", word); 66 | } 67 | } 68 | } 69 | ``` -------------------------------------------------------------------------------- /src/safe-guides/code_style/comments/P.CMT.04.md: -------------------------------------------------------------------------------- 1 | # P.CMT.04 File header comments include a copyright notice 2 | 3 | **[Description]** 4 | 5 | File header (i.e., module-level) comments should include the copyright notice first. If additional content needs to be added to the file header comments, it can be added under the copyright notice. 6 | 7 | May include: 8 | 9 | 1. A description of the function of the document. 10 | 2. Author. 11 | 3. Creation date and last modification date. 12 | 4. Notes. 13 | 5. Open source license (e.g., Apache 2.0, BSD, LGPL, GPL). 14 | 6. Other. 15 | 16 | The format of the copyright notice is as follows: 17 | 18 | - 中文版：`版权所有（c）XXX 技术有限公司 2015-2022`。 19 | - English version: `Copyright (c) XXX Technologies Co. Ltd. 2015-2022. All rights reserved. Licensed under Apache-2.0.` 20 | 21 | Its content can be adjusted to participate in the following detailed description: 22 | 23 | - `2015-2022` can be modified as needed. 2015 is the year the file was first created and 2022 is the year the file was last modified. It is possible to write only one creation year, so that the copyright notice does not need to be changed if the file is modified frequently. 24 | - For internal use, there is no need to add `All rights reserved`. 25 | - `Licensed under Apache-2.0.`, if it is open source then you can add the license statement. 26 | 27 | Caution when writing copyright notes: 28 | 29 | - Copyright notes should be written from the top of the file header. 30 | - The header comment should contain the "copyright notice" first, followed by the rest of the content. 31 | - Optional content should be added as needed to avoid empty formatting without content. 32 | - Maintain uniform formatting, either by the project or by the larger context. 33 | - Maintain a neat layout, with line breaks aligned. 34 | 35 | **[Good Case]** 36 | 37 | ```rust 38 | // Good 39 | // 版权所有（c）XXX 技术有限公司 2015-2022。 40 | 41 | // Or 42 | 43 | // Good 44 | // Copyright (c) XXX Technologies Co.Ltd. 2015-2022. 45 | // All rights reserved. Licensed under Apache-2.0. 46 | ``` -------------------------------------------------------------------------------- /src/safe-guides/code_style/comments/P.CMT.03.md: -------------------------------------------------------------------------------- 1 | # P.CMT.03 Use line comments and avoid block comments 2 | 3 | **[Description]** 4 | 5 | Try to use line comments (`//` or `///`) rather than block comments. This is a convention in the Rust community. 6 | 7 | For documentation comments, use `//! `, in other cases `///` is better. 8 | 9 | Note: `#! [doc]` and `#[doc]` have a special role in simplifying document comments, and it is not necessary to force them into `//! ` or `//`. 10 | 11 | **[Bad Case]** 12 | 13 | ```rust 14 | // Bad 15 | 16 | /* 17 | * Wait for the main task to return, and set the process error code 18 | * appropriately. 19 | */ 20 | mod tests { 21 | //! This module contains tests 22 | 23 | // ... 24 | } 25 | ``` 26 | 27 | **[Good Case]** 28 | 29 | When `normalize_comments = true`: 30 | 31 | ```rust 32 | // Good 33 | 34 | // Wait for the main task to return, and set the process error code 35 | // appropriately. 36 | 37 | // Good 38 | // When defining modules using the `mod` keyword, 39 | // it is better to use `///` on top of `mod`. 40 | 41 | /// This module contains tests 42 | mod tests { 43 | // ... 44 | } 45 | 46 | // Good 47 | #[doc = "Example item documentation"] 48 | pub enum Foo {} 49 | ``` 50 | 51 | **【rustfmt configuration】** 52 | 53 | | Parameter | Optional | Stable or not | Description | 54 | | -------------------------------------------------------------------------------------------- | -------------------------------- | ------------- | ------------------------------------------------------------------- | 55 | | [`normalize_comments`](https://rust-lang.github.io/rustfmt/?#normalize_comments) | false(default) true(suggestionn) | No | Convert the `/**/` comment to `/` | 56 | | [`normalize_doc_attributes`](https://rust-lang.github.io/rustfmt/?#normalize_doc_attributes) | false(default) | No | Convert the `#! [doc]` and `#[doc]` annotations to `//! ` and `///` | -------------------------------------------------------------------------------- /src/safe-guides/code_style/comments/P.CMT.02.md: -------------------------------------------------------------------------------- 1 | # P.CMT.02 Comments should have a width limit 2 | 3 | **[Description]** 4 | 5 | The width of each comment line should not be too long and needs to be set at a certain width, no more than 120, which help improve readability. 6 | 7 | In `rustfmt`, the `comment_width` with `wrap_comments` configuration item can automatically split comments that exceed the width limit into multiple lines. 8 | 9 | **Note**: The `use_small_heuristics` configuration item of `rustfmt` does not include `comment_width`. 10 | 11 | **[Bad Case]** 12 | 13 | ```rust 14 | // Bad 15 | // 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. 16 | ``` 17 | 18 | **[Good Case]** 19 | 20 | When `comment_width=80` and `wrap_comments=true`. 21 | 22 | **Note**: Here `wrap_comments` does not use the default value and needs to be configured to true. 23 | 24 | ```rust 25 | // Good 26 | // Lorem ipsum dolor sit amet, consectetur adipiscing elit, 27 | // sed do eiusmod tempor incididunt ut labore et dolore 28 | // magna aliqua. Ut enim ad minim veniam, quis nostrud 29 | // exercitation ullamco laboris nisi ut aliquip ex ea 30 | // commodo consequat. 31 | ``` 32 | 33 | **[rustfmt configuration]** 34 | 35 | | Parameter | Optional | stable or not | Description | 36 | | ---------------------------------------------------------------------- | -------------------------------- | ------------- | ---------------------------------------------------------------------------------------- | 37 | | [`comment_width`](https://rust-lang.github.io/rustfmt/?#comment_width) | 80(default) | No | Specify the maximum width allowed for a line of comments | 38 | | [`wrap_comments`](https://rust-lang.github.io/rustfmt/?#wrap_comments) | false(default), true(suggestion) | No | Running multi-line comments automatically change to multi-line comments by maximum width | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # Rust Coding Guidelines 2 | 3 | [《Rust 编码规范》 中文版](https://rust-coding-guidelines.github.io/rust-coding-guidelines-zh/) 4 | 5 | > WIP.See the Chinese version for the full version, the English version is currently being translated from the Chinese version, welcome to participate in the contribution! 6 | 7 | 8 | ## Introduce 9 | 10 | It is understood that some companies and organizations within the Rust community maintain their own coding specifications. Some of the publicly available ones are listed below. 11 | 12 | 13 | - [Rust API Guidelines](https://rust-lang.github.io/api-guidelines/about.html) 14 | - [Rust Style Guide](https://github.com/rust-dev-tools/fmt-rfcs/blob/master/guide/guide.md) 15 | - [Rust's Unsafe Code Guidelines Reference](https://rust-lang.github.io/unsafe-code-guidelines/) 16 | - [ANSSI | Secure Rust Guidelines](https://anssi-fr.github.io/rust-guide) 17 | - [PingCAP | Rust Style Guide](https://github.com/pingcap/style-guide) 18 | - [Google Fuchsia OS Rust Guide](https://fuchsia.dev/fuchsia-src/development/languages/rust) 19 | - [RustAnalyzer Style Guide](https://github.com/rust-analyzer/rust-analyzer/blob/master/docs/dev/style.md) 20 | - [Clippy lints](https://rust-lang.github.io/rust-clippy/master/index.html) 21 | - [lints in the rustc book ](https://doc.rust-lang.org/rustc/lints/listing/allowed-by-default.html) 22 | - [Noisy Clippy](https://github.com/dtolnay/noisy-clippy) 23 | - [Rustfmt Rules](https://rust-lang.github.io/rustfmt/?version=v1.4.38&search=) 24 | 25 | ## The role of coding specifications 26 | 27 | 1. Improve the readability, maintainability, robustness, and portability of code by following Rust language features. 28 | 2. Improve the standardization and security of Unsafe Rust code writing. 29 | 3. The programming specification terms strive to systematize, easy to apply, easy to check, to help developers improve development efficiency. 30 | 4. give developers a clear and global vision, in the process of developing code can follow a good code specification, rather than wait until the code is written and then through rustfmt and clippy such tools, a line to modify the warning. 31 | 5. The specification is not a tutorial, but the level of developers varies. For some knowledge blind spots and those that may lead to program errors, the specification will also cover. 32 | 33 | -------------------------------------------------------------------------------- /src/overview.md: -------------------------------------------------------------------------------- 1 | # Overview 2 | 3 | [《Rust 编码规范》 中文版](https://rust-coding-guidelines.github.io/rust-coding-guidelines-zh/) 4 | 5 | > WIP.See the Chinese version for the full version, the English version is currently being translated from the Chinese version, welcome to participate in the contribution! 6 | 7 | ## Lists 8 | 9 | - [1.1 Why you need the Rust coding specification ?](./overview/why.md) 10 | - [1.2 Basic conventions of the coding specification](./overview/convention.md) 11 | 12 | ## Introduce 13 | 14 | It is understood that some companies and organizations within the Rust community maintain their own coding specifications. Some of the publicly available ones are listed below. 15 | 16 | 17 | - [Rust API Guidelines](https://rust-lang.github.io/api-guidelines/about.html) 18 | - [Rust Style Guide](https://github.com/rust-dev-tools/fmt-rfcs/blob/master/guide/guide.md) 19 | - [Rust's Unsafe Code Guidelines Reference](https://rust-lang.github.io/unsafe-code-guidelines/) 20 | - [ANSSI | Secure Rust Guidelines](https://anssi-fr.github.io/rust-guide) 21 | - [PingCAP | Rust Style Guide](https://github.com/pingcap/style-guide) 22 | - [Google Fuchsia OS Rust Guide](https://fuchsia.dev/fuchsia-src/development/languages/rust) 23 | - [RustAnalyzer Style Guide](https://github.com/rust-analyzer/rust-analyzer/blob/master/docs/dev/style.md) 24 | - [Clippy lints](https://rust-lang.github.io/rust-clippy/master/index.html) 25 | - [lints in the rustc book ](https://doc.rust-lang.org/rustc/lints/listing/allowed-by-default.html) 26 | - [Noisy Clippy](https://github.com/dtolnay/noisy-clippy) 27 | - [Rustfmt Rules](https://rust-lang.github.io/rustfmt/?version=v1.4.38&search=) 28 | 29 | ## The role of coding specifications 30 | 31 | 1. Improve the readability, maintainability, robustness, and portability of code by following Rust language features. 32 | 2. Improve the standardization and security of Unsafe Rust code writing. 33 | 3. The programming specification terms strive to systematize, easy to apply, easy to check, to help developers improve development efficiency. 34 | 4. Give developers a clear and global vision, in the process of developing code can follow a good code specification, rather than wait until the code is written and then through `rustfmt` and `clippy` such tools, a line to modify the warning. 35 | 5. The specification is not a tutorial, but the level of developers varies. For some knowledge blind spots and those that may lead to program errors, the specification will also cover. 36 | -------------------------------------------------------------------------------- /src/safe-guides/code_style/comments/P.CMT.01.md: -------------------------------------------------------------------------------- 1 | # P.CMT.01 The code can be self-annotated, and the documentation should be concise 2 | 3 | **[Description]** 4 | 5 | 一、The code can be self-annotated, avoiding redundant ordinary code comments. 6 | 7 | Comments are important, but the best code is documentation itself. Meaningful type, function, and variable names are far better than ambiguous names explained by comments. Comments are used when meaningful type names, function names, and variable names cannot express complete semantics. 8 | 9 | Don't describe obvious phenomena, and never translate code in natural language as comments. 10 | 11 | 二、The documentation should be concise. 12 | 13 | 1. The content and terms in the documentation comments should be as short and concise as possible, and should not be too long. Make sure your code is well commented and understandable by others. Good comments convey the context and purpose of the code. 14 | 2. Comments are always structured around two key points: 15 | - What: Used to describe what the code implement. 16 | - How: Used to describe how to use code your code. 17 | 3. The natural language used for comments and documentation comments should be consistent. 18 | 4. Rust project documentation should always be built on the `rustdoc` tool. `rustdoc` supports the Markdown format. To make the documentation more beautiful and readable, the documentation comments should use the Markdown format. 19 | 20 | **[Good Case]** 21 | 22 | Module Based Documentation Comments. From Rust std `std::vec`: 23 | 24 | ```rust 25 | // Good 26 | 27 | //! # The Rust core allocation and collections library 28 | //! 29 | //! This library provides smart pointers and collections for managing 30 | //! heap-allocated values. 31 | //! 32 | //! This library, like libcore, normally doesn’t need to be used directly 33 | //! since its contents are re-exported in the [`std` crate](../std/index.html). 34 | //! Crates that use the `#![no_std]` attribute however will typically 35 | //! not depend on `std`, so they’d use this crate instead. 36 | //! 37 | //! ## Boxed values 38 | //! 39 | //! The [`Box`] type is a smart pointer type. There can only be one owner of a 40 | //! [`Box`], and the owner can decide to mutate the contents, which live on the 41 | //! heap. 42 | ``` 43 | 44 | General Documentation Comments. From Rust std `Vec::new` method. 45 | 46 | ```rust 47 | // Good 48 | 49 | /// Constructs a new, empty `Vec`. 50 | /// 51 | /// The vector will not allocate until elements are pushed onto it. 52 | /// 53 | /// # Examples 54 | /// 55 | /// ``` 56 | /// # #![allow(unused_mut)] 57 | /// let mut vec: Vec = Vec::new(); 58 | /// ``` 59 | #[inline] 60 | #[rustc_const_stable(feature = "const_vec_new", since = "1.39.0")] 61 | #[stable(feature = "rust1", since = "1.0.0")] 62 | pub const fn new() -> Self { 63 | Vec { buf: RawVec::NEW, len: 0 } 64 | } 65 | ``` -------------------------------------------------------------------------------- /src/safe-guides/coding_practice/fn-design/G.FUD.04.md: -------------------------------------------------------------------------------- 1 | # G.FUD.04 Should input by-value but by-ref if parameter derived `Copy`, and its value is a small enough number 2 | 3 | **[Level] Advice** 4 | 5 | **[Description]** 6 | 7 | Generally, it is avoided to input by-ref when parameter's value is a small enough number and derived `Copy`. That's because as for such small values, from the perspective of performance, by-value is as fast as by-ref, and it could also make code more readable. It is also recommended to input by-value for some tiny `struct`, but should notice **[Exception]** cases. 8 | 9 | **[Bad Case]** 10 | 11 | ```rust 12 | #![warn(clippy::trivially_copy_pass_by_ref)] 13 | 14 | // Not Good 15 | fn foo(v: &u32) { ... } 16 | ``` 17 | 18 | **[Good Case]** 19 | 20 | ```rust 21 | #![warn(clippy::trivially_copy_pass_by_ref)] 22 | 23 | // Good 24 | fn foo(v: u32) { ... } 25 | ``` 26 | 27 | **[Exception]** 28 | 29 | Should notice following cases, lint checker would report trivial warnings because of its conservativeness. 30 | 31 | ```rust 32 | #[derive(Clone, Copy)] 33 | struct RawPoint { 34 | pub x: u8, 35 | } 36 | 37 | #[derive(Clone, Copy)] 38 | struct Point { 39 | pub raw: RawPoint, 40 | } 41 | 42 | impl Point { 43 | pub fn raw(&self) -> *const RawPoint { 44 | &self.raw 45 | } 46 | 47 | // if you conform lint checker, change above `raw(&self)`'s parameter `&self` into `self`(delete ref), it is `raw_linted(self)`. That also works well in unoptimized cases(just like `cargo build`, the debug mode), but doesn't work in optimized cases(i.e. `cargo build --release`, the release mode) because of following reasons. 48 | pub fn raw_linted(self) -> *const RawPoint { 49 | &self.raw 50 | } 51 | } 52 | 53 | fn main() { 54 | let p = Point { raw: RawPoint { x: 10 } }; 55 | 56 | // This passes 57 | assert_eq!(p.raw(), p.raw()); 58 | 59 | // This fails 60 | // Actually, in optimized cases, the activity of function has been changed if not using `self` as shared ref. 61 | // Because struct Point derived Copy trait, everytime we call raw_linted() method, its instance would be copied, and return a different pointer. 62 | assert_eq!(p.raw_linted(), p.raw_linted()); 63 | } 64 | ``` 65 | 66 | **[Lint Check]** 67 | 68 | | lint name | Clippy check | Rustc check | Lint Group | Level | 69 | | --------- | ------------ | ----------- | ---------- | ----- | 70 | | [trivially_copy_pass_by_ref](https://rust-lang.github.io/rust-clippy/master/#trivially_copy_pass_by_ref) | yes | no | pedanic | allow | 71 | 72 | This lint corresponds to the following configuration of `clippy.toml` 73 | 74 | ```toml 75 | # if it is an exported API, the lint checker would not be triggered, which avoid unexpected modifications. 76 | avoid-breaking-exported-api=true 77 | 78 | # consider the maximum size (bytes) of by-value pass with Copy. The default is None. 79 | trivial-copy-size-limit=None 80 | ``` 81 | **Tips:** this lint would not consider the cases using pointer, just like example in **[Exception]** part. 82 | 83 | Reference of **[Exception]** example: [rust-clippy/issues/5953](https://github.com/rust-lang/rust-clippy/issues/5953). -------------------------------------------------------------------------------- /src/safe-guides/code_style/naming/P.NAM.05.md: -------------------------------------------------------------------------------- 1 | ## P.NAM.05 The `getter` family of methods used to access or retrieve data should not normally have the prefix `get_` 2 | 3 | **[Description]** 4 | 5 | Because of Rust's ownership semantics, both methods' parameters in following cases use shared reference `&self` or exclusive reference `&mut self` , which represent `getter` semantics. 6 | 7 | > `getter` semantics always mean to return an object but a reference in Rust's ownership conventions. 8 | 9 | There are also some exceptions to use `get_` prefix. 10 | 11 | 12 | **[Bad Case]** 13 | ```rust 14 | pub struct First; 15 | pub struct Second; 16 | 17 | pub struct S { 18 | first: First, 19 | second: Second, 20 | } 21 | 22 | impl S { 23 | // Bad: Shouldn't use 'get_' prefix to name accesssing member function. 24 | pub fn get_first(&self) -> &First { 25 | &self.first 26 | } 27 | 28 | // Bad： 29 | // `get_mut_first`, or `mut_first` are also not good. 30 | pub fn get_first_mut(&mut self) -> &mut First { 31 | &mut self.first 32 | } 33 | 34 | // set_ prefix is fine. 35 | pub fn set_first(&mut self, f: First) -> &mut First { 36 | self.first = f; 37 | } 38 | } 39 | ``` 40 | 41 | 42 | **[Good Case]** 43 | 44 | ```rust 45 | pub struct First; 46 | pub struct Second; 47 | 48 | pub struct S { 49 | first: First, 50 | second: Second, 51 | } 52 | 53 | impl S { 54 | // Ok 55 | pub fn first(&self) -> &First { 56 | &self.first 57 | } 58 | 59 | // Ok 60 | pub fn first_mut(&mut self) -> &mut First { 61 | &mut self.first 62 | } 63 | 64 | // set_ prefix is fine. 65 | pub fn set_first(&mut self, f: First) -> &mut First { 66 | self.first = f; 67 | } 68 | } 69 | ``` 70 | 71 | **[Exception]** 72 | 73 | However, there are also some exceptions: Only in cases to retrieve data by `getter` explicitly, could name with `get_` prefix. For example, `Cell::get` could access the data in one `Cell`. 74 | 75 | For `getter` checked in runtime, such as bounds checking, we could consider to add an Unsafe `_unchecked` methods. Generally, there would be following function signatures. 76 | 77 | ```rust 78 | // Do some checks in runtime, such as bounds checking. 79 | fn get(&self, index: K) -> Option<&V>; 80 | fn get_mut(&mut self, index: K) -> Option<&mut V>; 81 | // No runtime checking, use to improve performance in some case. 82 | // For example, when executed in an execution environment,which is impossible to trigger bounds checking. 83 | unsafe fn get_unchecked(&self, index: K) -> &V; 84 | unsafe fn get_unchecked_mut(&mut self, index: K) -> &mut V; 85 | ``` 86 | There is almost no such distinction between `getter` and type conversion ([G.NAM.02](./G.NAM.02.md)). For instance, [`TemDir::path`](https://docs.rs/tempdir/0.3.7/tempdir/struct.TempDir.html#method.path) could be regarded as a `getter`, which represents the filesystem's path of temporary directory, and [`TemDir::into_path`](https://docs.rs/tempdir/0.3.7/tempdir/struct.TempDir.html#method.into_path) is in charge of sending converted data when deleting temporary directory 87 | to callee. 88 | 89 | There would not result for redundancy with naming the method as `path`, because `path` itself is a `getter`, otherwise if you name it as `get_path` or `as_path`. 90 | 91 | [`TempDir::path`]: https://docs.rs/tempdir/0.3.7/tempdir/struct.TempDir.html#method.path 92 | [`TempDir::into_path`]: https://docs.rs/tempdir/0.3.7/tempdir/struct.TempDir.html#method.into_path 93 | 94 | Implementations in `StandardLibrary`: 95 | 96 | - [`std::io::Cursor::get_mut`](https://doc.rust-lang.org/std/io/struct.Cursor.html#method.get_mut) 97 | - [`std::ptr::Unique::get_mut`](https://doc.rust-lang.org/std/ptr/struct.Unique.html#method.get_mut) 98 | - [`std::sync::PoisonError::get_mut`](https://doc.rust-lang.org/std/sync/struct.PoisonError.html#method.get_mut) 99 | - [`std::sync::atomic::AtomicBool::get_mut`](https://doc.rust-lang.org/std/sync/atomic/struct.AtomicBool.html#method.get_mut) 100 | - [`std::collections::hash_map::OccupiedEntry::get_mut`](https://doc.rust-lang.org/std/collections/hash_map/struct.OccupiedEntry.html#method.get_mut) 101 | - [`<[T]>::get_unchecked`](https://doc.rust-lang.org/std/primitive.slice.html#method.get_unchecked) 102 | -------------------------------------------------------------------------------- /src/safe-guides/overview/why.md: -------------------------------------------------------------------------------- 1 | # 1.1 Why you need the Rust coding specification ? 2 | 3 | When I first learned Rust, I marveled at the sophistication of the tools Rust provides. For example, `rustfmt`, which automatically formats code, and `clippy`, which helps you standardize code that is not written properly. They are truly excellent tools. At the time, I didn't think Rust needed to be coded at all like other languages. 4 | 5 | But as I learned more and more about Rust, I came to realize that these tools had a lot of shortcomings and did not cover everything. For example, improper configuration and use of rustfmt can lead to code errors and inability to recognize the semantics of various naming in Rust code; clippy has some false positives or lint is not reasonable, and can not cover to Unsafe Rust and other issues. Developers, especially newcomers, if they rely on `rutfmt` and `clippy` for a long time like using a black box, but do not understand the reason behind their lint, just know the reason but not the reason. it is impossible to improve the development efficiency under the premise that the code quality has certain requirements. 6 | 7 | So, `rutfmt` and `clippy` are not a panacea. We also need a comprehensive and universal coding specification that also covers tools like `rustfmt` and `clippy`, so that the majority of Rust teams can quickly implement Rust and enhance collaboration and trust between teams by standardizing the principles and rules to understand the basic framework for writing authentic Rust code. 8 | 9 | ## Limitations of Rustfmt and Clippy 10 | 11 | ### Limitations of Rustfmt 12 | 13 | Rust has an automatic formatting tool, rustfmt, which helps developers get rid of the manual work of formatting code and increase productivity. However, it does not replace the coding specification to standardize the coding style of Rust code. 14 | 15 | The main drawbacks of rustfmt are the following. 16 | 17 | 1. The naming of variables, types, functions, etc. in Rust contains semantics, especially ownership semantics. rustfmt tool cannot determine the naming semantics in the code. This aspect can be partially satisfied by using Clippy, but it is rather one-sided for developers. 18 | 2. rustfmt can cause problems if used improperly or configured improperly. Because rustfmt is an auto-formatting tool, it automatically modifies the code, but it does not compile when it modifies the code. If the developer configures autosave and then executes rustfmt automatically, it will cause the code to be modified incorrectly. Or, there are some configuration options for rustfmt that are misconfigured, which will also cause the code to be modified incorrectly. 19 | 3. The configuration items of rustfmt tool are fragmented, and most developers do not understand the meaning of each configuration item. 20 | 4. rustfmt does not have a coding specification that covers code comments and documentation comments. 21 | 22 | In summary, there is a particular need to provide a common coding specification so that developers clearly understand what coding style Rust follows overall in terms of naming, formatting and commenting. It will cover the content of rustfmt, but not mechanically extract the rules of rustfmt one by one, but a unified categorization and organization of the rules of rustfmt, to facilitate developers to understand the rules set in rustfmt, and to facilitate the team to form their own code style. 23 | 24 | ### Clippy's limitations 25 | 26 | Clippy is a linter for Rust, one of the main components of the Rust ecosystem. It performs additional static checks on developed code, reports problems found and explains how to fix them (sometimes it can even fix them automatically). Using it can be beneficial for Rust beginners and even professionals. 27 | 28 | However, using Clippy does not mean that it can replace coding specifications, and it has many drawbacks: 29 | 30 | 1. Unsafe Rust is a very important part of Rust and needs to be covered by a complete coding specification to help developers write safe Unsafe code. 31 | 2. there are more than 500 lint in Clippy so far, and there is a growing trend. it is impossible for developers to understand each lint one by one, so a coding specification is needed to help developers to sort out and categorize lint. 32 | 3. there is some controversy about the suggestion and classification (allow/warning/deny) of lint in Clippy. Some lint is allow by default, but it does not mean that it is reasonable to write in some scenarios; similarly, some lint is warning, but it does not mean that it is unreasonable in some scenarios. For this reason, dtolnay also created this repository: [https://github.com/dtolnay/noisy-clippy](https://github.com/dtolnay/noisy-clippy) for analyzing how many Clippy lint's in the community crate suggestions does not match the actual scenario, so as to achieve the goal of improving Clippy. 33 | 34 | In summary, Clippy is a very useful tool, but it is not a replacement for coding specifications. -------------------------------------------------------------------------------- /src/safe-guides/overview/convention.md: -------------------------------------------------------------------------------- 1 | # 1.2 Basic conventions of the coding specification 2 | 3 | **Programming specifications are in no way written to increase the burden on developers and are intended to help developers write high-quality Rust code.** 4 | 5 | To accomplish this, the specification terms are divided into two categories: **Principles** and **Rules**. 6 | 7 | - A principle is a general direction that guides programming development, or refers to a class of situations. There are also a few principles that are detectable by the Rust compiler, but because the compiler diagnostic information is confusing, principles are added to help developers avoid such situations. 8 | 9 | - Rules, as opposed to principles, are more specific and contain positive and negative examples to further illustrate them. Some rules also add exceptions. The rules are basically detectable by lint. 10 | 11 | ## Rule content Relationship with rustfmt and clippy 12 | 13 | The specification is divided into two main parts: code style and code practice. 14 | 15 | **Code style** 16 | 17 | Code naming, formatting and comments are included in the code style. 18 | 19 | - The naming part, mainly by clippy lint to check, some naming rules clippy lint does not provide detection, then need to custom lint to support. 20 | - The format part, mainly using rustfmt to automatically modify, the rules in the coding specification describes most of the configuration items of rustfmt by category, in order to facilitate developers to make reference and develop their own configuration items. Configuration templates are also provided in the coding specification. 21 | - The comments section, which includes general comments and documentation comments, rule entries are regulated through a collaboration between rustfmt and clippy. 22 | 23 | **Code Practices** 24 | 25 | The code practices are categorized by Rust language features, and each language feature is summarized as much as possible for everyday coding best practices, extracted into a list of principles and rules for developers to refer to. Most of the rules are recommendations, and the rules that are required are basically security-related. 26 | 27 | Clippy lint involves a lot of skillful lint, so it is not put into the specification. 28 | 29 | The **rules mainly focus on generic scenarios, code readability, maintainability, security, performance of the four considerations, it only covers a small part (less than 1/5) clippy lint**. There are also rules that are not available in the clippy lint and require custom lint. 30 | 31 | The focus of the code practice content is on the Unsafe Rust coding specification, which has more coding principles than rules, and which is rarely detected by Clippy lint. There are more rules that require classes. 32 | 33 | We hope that this section will help developers avoid some common pitfalls in writing Rust code. 34 | 35 | ## Coding specification content conventions 36 | 37 | Identified by the number before the title. 38 | 39 | - Identified as `P` for Principle. Numbered as `P.Element.Number`. 40 | - Identified as `G` for Rule (Guideline). The numbering is `G.Element.Number`. 41 | - When there are subdirectories. Number is `P.Element.SubElement.Number` or `G.Element.SubElement.Number`. 42 | 43 | Number is incremented from `01`. Where `Element` is the three-letter abbreviation for the key element (corresponding to the secondary catalog in this specification) in the domain knowledge. (Terminology reference: [SEI CERT C Coding Standard](https://wiki.sei.cmu.edu/confluence/display/c/SEI+CERT+C+Coding+Standard)) 44 | 45 | 46 | | Element | Explanation | Element | Explanation | 47 | | ------- | ------ | ------- | -------- | 48 | | NAM | 命名 (Naming) | CMT | 注释 (Comment) | 49 | | FMT | 格式 (Format) | TYP | 数据类型 (Data Type) | 50 | | CNS | 常量 (Const) | VAR | 变量 (Variables) | 51 | | EXP | 表达式 (Expression) | CTF | 控制流程 (Control Flow) | 52 | | REF | 引用 (Reference) | PTR | 指针 (Pointer) | 53 | | STR | 字符串 (String) | INT | 整数 (Integer) | 54 | | MOD | 模块 (Module) | CAR | 包管理 (Cargo) | 55 | | MEM | 内存 (Memory) | FUD | 函数设计 (Function Design) | 56 | | MAC | 宏 (Macro) | STV | 静态变量 (Static Variables) | 57 | | GEN | 泛型 (Generic) | TRA | 特质 (Trait) | 58 | | ASY | 异步 (Async) | UNS | 非安全 (Unsafe Rust) | 59 | | SAS | 安全抽象 (Safety Abstract) | FFI | 外部函数调用接口 ( Foreign Function Interface ) | 60 | | LAY | 内存布局 (Layout) | ERR | 错误处理 (Error Handle) | 61 | | CLT | 集合 (Collection) | MTH | 多线程 (Multi Threads) | 62 | | EMB | 嵌入式Rust (Embedded Rust) | FIO | 输入输出 (In/Out) | 63 | | SEC | 信息安全 (Security) | SPT | 智能指针 (Smart Pointer) | 64 | | UNT | 单元类型 (Unit) | BOL | 布尔 (Bool) | 65 | | CHR | 字符类型 (Char) | FLT | 浮点数 (Float) | 66 | | SLC | 切片类型 (Slice) | TUP | 元组 (Tuple) | 67 | | ARR | 固定长度数组类型 (Array) | VEC | 动态长度数组 (Vector) | 68 | | SCT | 结构体 (Struct) | ENM | 枚举体 (Enum) | 69 | | UNI| 联合体 (Union) | BLN | 标准库内置（BuiltIn） | 70 | | OBJ | Trait 对象 (Trait Object)| LFT| 生命周期 (Lifetime) | 71 | | BOX | `Box` 类型 | DRP | 析构函数 (Drop) | 72 | | DCL | 声明宏 (Declarative) | PRO | 过程宏 (Procedural) | 73 | | LCK | 锁同步 (Lock) | LKF | 无锁 (Lock Free) | 74 | | | | OTH | 其他 (Ohters) | 75 | 76 | ## Reference code open source license description 77 | 78 | All references to external code in this specification meet the `MIT/Apache/Mozilla public licenses` open source license! -------------------------------------------------------------------------------- /src/SUMMARY.md: -------------------------------------------------------------------------------- 1 | # Rust Coding Specification 2 | 3 | - [Overview](./overview.md) 4 | - [Why you need the Rust coding specification ](./safe-guides/overview/why.md) 5 | - [Basic conventions of the coding specification](./safe-guides/overview/convention.md) 6 | - [Coding Style](./safe-guides/code_style.md) 7 | - [Naming](./safe-guides/code_style/naming.md) 8 | - [P.NAM.01 The naming convention for identifiers in the same crate should use a uniform word order](./safe-guides/code_style/naming/P.NAM.01.md) 9 | - [P.NAM.02 Names for cargo features should not contain meaningless placeholders](./safe-guides/code_style/naming/P.NAM.02.md) 10 | - [P.NAM.03 Identifier naming should be in line with reading habits](./safe-guides/code_style/naming/P.NAM.03.md) 11 | - [P.NAM.04 The larger the scope, the more precise the naming, and the opposite should be short](./safe-guides/code_style/naming/P.NAM.04.md) 12 | - [P.NAM.05 The `getter` family of methods used to access or retrieve data should not normally have the prefix `get_`](./safe-guides/code_style/naming/P.NAM.05.md) 13 | - [P.NAM.06 Follow the `iter/ iter_mut/ into_iter` specification to generate iterators](./safe-guides/code_style/naming/P.NAM.06.md) 14 | - [P.NAM.07 Avoid using special names such as language built-in reserved words, keywords, built-in types and traits](./safe-guides/code_style/naming/P.NAM.07.md) 15 | - [P.NAM.08 Avoid adding type identifiers to the naming of variables](./safe-guides/code_style/naming/P.NAM.08.md) 16 | - [P.NAM.09 Global static variables should be defined with the prefix `G_` to distinguish them from constants](./safe-guides/code_style/naming/P.NAM.09.md) 17 | - [G.NAM.01 Use a uniform naming style](./safe-guides/code_style/naming/G.NAM.01.md) 18 | - [G.NAM.02 Type conversion function naming needs to follow ownership semantics](./safe-guides/code_style/naming/G.NAM.02.md) 19 | - [Format](./safe-guides/code_style/fmt.md) 20 | - [P.FMT.01 Automatic code formatting with rustfmt](./safe-guides/code_style/fmt/P.FMT.01.md) 21 | - [P.FMT.02 Use spaces instead of tabs for indentation](./safe-guides/code_style/fmt/P.FMT.02.md) 22 | - [P.FMT.03 The maximum width of line spacing is one blank line](./safe-guides/code_style/fmt/P.FMT.03.md) 23 | - [P.FMT.04 Language items should be defined with the left braces position on the same line ](./safe-guides/code_style/fmt/P.FMT.04.md) 24 | - [P.FMT.05 Block indentation should be maintained when multiple identifiers are present](./safe-guides/code_style/fmt/P.FMT.05.md) 25 | - [P.FMT.06 When there is a multi-line expression operation, the operator should be placed at the beginning of the line](./safe-guides/code_style/fmt/P.FMT.06.md) 26 | - [P.FMT.07 Both enumeration variants and structure fields should be left aligned](./safe-guides/code_style/fmt/P.FMT.07.md) 27 | - [P.FMT.08 Line feeds for functions with more than five parameters or imported modules with more than four parameters](./safe-guides/code_style/fmt/P.FMT.08.md) 28 | - [P.FMT.09 Use different spaces style for different scenarios](./safe-guides/code_style/fmt/P.FMT.09.md) 29 | - [P.FMT.10 `match` arms should have good readability](./safe-guides/code_style/fmt/P.FMT.10.md) 30 | - [P.FMT.11 Imported modules should be grouped with good readability](./safe-guides/code_style/fmt/P.FMT.11.md) 31 | - [P.FMT.12 Declarative macros arms should be well readable](./safe-guides/code_style/fmt/P.FMT.12.md) 32 | - [P.FMT.13 Do not omit field names when initializing named structure fields](./safe-guides/code_style/fmt/P.FMT.13.md) 33 | - [P.FMT.14 `extern` external functions need to be explicitly specified `C-ABI`](./safe-guides/code_style/fmt/P.FMT.14.md) 34 | - [P.FMT.15 Deconstructing a tuple allows the use of `.. ` to refer to the remaining elements](./safe-guides/code_style/fmt/P.FMT.15.md) 35 | - [P.FMT.16 Do not merge multiple unrelated traits in derived macros into the same line](./safe-guides/code_style/fmt/P.FMT.16.md) 36 | - [Code Comments](./safe-guides/code_style/comments.md) 37 | - [P.CMT.01 The code can be self-commenting and the documentation should be concise.](./safe-guides/code_style/comments/P.CMT.01.md) 38 | - [P.CMT.02 Comments should have a width limit](./safe-guides/code_style/comments/P.CMT.02.md) 39 | - [P.CMT.03 Use line comments and avoid block comments](./safe-guides/code_style/comments/P.CMT.03.md) 40 | - [P.CMT.04 File header comments include a copyright notice](./safe-guides/code_style/comments/P.CMT.04.md) 41 | - [P.CMT.05 Use FIXME and TODO in comments to help with team collaboration](./safe-guides/code_style/comments/P.CMT.05.md) 42 | - [G.CMT.01 Error comments need to be added to the documentation of functions that return `Result` types in the public](./safe-guides/code_style/comments/G.CMT.01.md) 43 | - [G.CMT.02 If a Panic occurs under certain circumstances in the public API, add a Panic comment to the corresponding document](./safe-guides/code_style/comments/G.CMT.02.md) 44 | - [G.CMT.03 Use spaces in document comments instead of tabs](./safe-guides/code_style/comments/G.CMT.03.md) 45 | - [Coding Practice](./safe-guides/coding_practice.md) 46 | - [Const](./safe-guides/coding_practice/consts.md) 47 | - [G.CNS.01 Use predefined consts for float approximation in scientific computation](./safe-guides/coding_practice/consts/G.CNS.01.md) 48 | - [G.CNS.02 Shouldn't assert const bool type](./safe-guides/coding_practice/consts/G.CNS.02.md) 49 | - [G.CNS.03 Shouldn't declare interior mutable container as consts](./safe-guides/coding_practice/consts/G.CNS.03.md) 50 | - [G.CNS.04 Shouldn't add explicit `'static` lifetime in constant declaration](./safe-guides/coding_practice/consts/G.CNS.04.md) 51 | - [G.CNS.05 Should use const fn as much as possible](./safe-guides/coding_practice/consts/G.CNS.05.md) 52 | - [Static Const](./safe-guides/coding_practice/statics.md) 53 | - [G.STV.01 Shouldn't use `static mut` as global variable directly](./safe-guides/coding_practice/statics/G.STV.01.md) 54 | - [Local Const](./safe-guides/coding_practice/variables.md) 55 | - [P.VAR.01 一般情况下避免先声明可变变量再赋值](./safe-guides/coding_practice/variables/P.VAR.01.md) 56 | - [P.VAR.02 利用变量遮蔽功能保证变量安全使用](./safe-guides/coding_practice/variables/P.VAR.02.md) 57 | - [G.VAR.01 以解构元组方式定义超过四个变量时不应使用太多无意义变量名](./safe-guides/coding_practice/variables/G.VAR.01.md) 58 | - [G.VAR.02 不应使用非 ASCII 字符作为标识符](./safe-guides/coding_practice/variables/G.VAR.02.md) 59 | - [G.VAR.03 变量遮蔽功能应当合理使用](./safe-guides/coding_practice/variables/G.VAR.03.md) 60 | - [G.VAR.04 避免因局部变量过大而导致的大量栈分配](./safe-guides/coding_practice/variables/G.VAR.04.md) 61 | - [Data Type](./safe-guides/coding_practice/data-type.md) 62 | - [P.TYP.01 必要时，应使类型可以表达更明确的语义，而不是只是直接使用原生类型](./safe-guides/coding_practice/data-type/P.TYP.01.md) 63 | - [G.TYP.01 类型转换尽可能使用安全的转换函数代替 as](./safe-guides/coding_practice/data-type/G.TYP.01.md) 64 | - [G.TYP.02 数字字面量在使用的时候应该明确标注类型](./safe-guides/coding_practice/data-type/G.TYP.02.md) 65 | - [G.TYP.03 不要用数字类型边界值判断能否安全转换，而应使用 try_from 方法](./safe-guides/coding_practice/data-type/G.TYP.03.md) 66 | - [Bool](./safe-guides/coding_practice/data-type/bool.md) 67 | - [G.TYP.BOL.01 不应将布尔值和布尔字面量进行比较](./safe-guides/coding_practice/data-type/bool/G.TYP.BOL.01.md) 68 | - [G.TYP.BOL.02 如果 match 匹配表达式为布尔类型，宜使用 if 表达式来代替](./safe-guides/coding_practice/data-type/bool/G.TYP.BOL.02.md) 69 | - [G.TYP.BOL.03 不应将数字类型转换为布尔值](./safe-guides/coding_practice/data-type/bool/G.TYP.BOL.03.md) 70 | - [G.TYP.BOL.04 禁止在if表达式条件中使用块结构](./safe-guides/coding_practice/data-type/bool/G.TYP.BOL.04.md) 71 | - [G.TYP.BOL.05 非必要时，布尔运算应使用逻辑运算符( &&/||)而非位运算符 (&/|)](./safe-guides/coding_practice/data-type/bool/G.TYP.BOL.05.md) 72 | - [G.TYP.BOL.06 不应使用数字代替布尔值](./safe-guides/coding_practice/data-type/bool/G.TYP.BOL.06.md) 73 | - [Character](./safe-guides/coding_practice/data-type/char.md) 74 | - [G.TYP.CHR.01 不应将字符字面量强制转换为 u8](./safe-guides/coding_practice/data-type/char/G.TYP.CHR.01.md) 75 | - [G.TYP.CHR.02 字符串方法中如果需要单个字符的值作为参数，宜使用字符而非字符串](./safe-guides/coding_practice/data-type/char/G.TYP.CHR.02.md) 76 | - [G.TYP.CHR.03 需要将整数转换为字符时，应使用安全转换函数，而非 transmute](./safe-guides/coding_practice/data-type/char/G.TYP.CHR.03.md) 77 | - [Integer](./safe-guides/coding_practice/data-type/int.md) 78 | - [G.TYP.INT.01 在用整数计算的时候需要考虑整数溢出、回绕和截断的风险](./safe-guides/coding_practice/data-type/int/G.TYP.INT.01.md) 79 | - [G.TYP.INT.02 避免在有符号整数和无符号整数之间进行强制转换](./safe-guides/coding_practice/data-type/int/G.TYP.INT.02.md) 80 | - [G.TYP.INT.03 对负数取模计算的时候不应使用 %](./safe-guides/coding_practice/data-type/int/G.TYP.INT.03.md) 81 | - [Float](./safe-guides/coding_practice/data-type/float.md) 82 | - [G.TYP.FLT.01 使用浮点数字面量时，要警惕是否存在被Rust编译器截断的风险](./safe-guides/coding_practice/data-type/float/G.TYP.FLT.01.md) 83 | - [G.TYP.FLT.02 从任何数字类型转换为浮点类型时注意避免损失精度](./safe-guides/coding_practice/data-type/float/G.TYP.FLT.02.md) 84 | - [G.TYP.FLT.03 对精度高要求的场景下，使用浮点数进行运算和比较时需要注意精度损失](./safe-guides/coding_practice/data-type/float/G.TYP.FLT.03.md) 85 | - [G.TYP.FLT.04 宜使用Rust内置方法处理浮点数计算](./safe-guides/coding_practice/data-type/float/G.TYP.FLT.04.md) 86 | - [G.TYP.FLT.05 禁止在浮点数和整数相互转换时使用 transmute](./safe-guides/coding_practice/data-type/float/G.TYP.FLT.05.md) 87 | - [Slice](./safe-guides/coding_practice/data-type/slice.md) 88 | - [P.TYP.SLC.01 宜使用切片迭代器来代替手工索引](./safe-guides/coding_practice/data-type/slice/P.TYP.SLC.01.md) 89 | - [P.TYP.SLC.02 宜使用切片模式来提升代码的可读性](./safe-guides/coding_practice/data-type/slice/P.TYP.SLC.02.md) 90 | - [Tuple](./safe-guides/coding_practice/data-type/tuple.md) 91 | - [G.TYP.TUP.01 使用元组时，其元素不宜超过3个](./safe-guides/coding_practice/data-type/tuple/G.TYP.TUP.01.md) 92 | - [Array](./safe-guides/coding_practice/data-type/array.md) 93 | - [G.TYP.ARR.01 创建大全局数组时宜使用静态变量而非常量](./safe-guides/coding_practice/data-type/array/G.TYP.ARR.01.md) 94 | - [G.TYP.ARR.02 使用数组索引时禁止越界访问](./safe-guides/coding_practice/data-type/array/G.TYP.ARR.02.md) 95 | - [G.TYP.ARR.03 当数组元素为原生数据类型（Primitive），排序时优先选用非稳定排序](./safe-guides/coding_practice/data-type/array/G.TYP.ARR.03.md) 96 | - [Vector](./safe-guides/coding_practice/data-type/vec.md) 97 | - [P.TYP.VEC.01 非必要时不宜使用动态数组](./safe-guides/coding_practice/data-type/vec/P.TYP.VEC.01.md) 98 | - [P.TYP.VEC.02 创建动态数组时，宜预先分配足够容量，避免后续操作中产生多次分配](./safe-guides/coding_practice/data-type/vec/P.TYP.VEC.02.md) 99 | - [G.TYP.VEC.01 禁止访问未初始化的数组](./safe-guides/coding_practice/data-type/vec/G.TYP.VEC.01.md) 100 | - [Struct](./safe-guides/coding_practice/data-type/struct.md) 101 | - [P.TYP.SCT.01 为结构体实现构造性方法时，避免构造后再初始化的情况](./safe-guides/coding_practice/data-type/struct/P.TYP.SCT.01.md) 102 | - [P.TYP.SCT.02 结构体实例需要默认实现时，宜使用Default特质](./safe-guides/coding_practice/data-type/struct/P.TYP.SCT.02.md) 103 | - [G.TYP.SCT.01 对外导出的公开的 Struct，宜添加#[non_exhaustive]属性](./safe-guides/coding_practice/data-type/struct/G.TYP.SCT.01.md) 104 | - [G.TYP.SCT.02 当结构体中有超过三个布尔类型的字段，宜将其独立为新的枚举类](./safe-guides/coding_practice/data-type/struct/G.TYP.SCT.02.md) 105 | - [G.TYP.SCT.03 宜使用结构体功能更新语法来提升代码可读性](./safe-guides/coding_practice/data-type/struct/G.TYP.SCT.03.md) 106 | - [Enumeration](./safe-guides/coding_practice/data-type/enum.md) 107 | - [G.TYP.ENM.01 合理使用map和and_then方法](./safe-guides/coding_practice/data-type/enum/G.TYP.ENM.01.md) 108 | - [G.TYP.ENM.02 不应自行创建空枚举](./safe-guides/coding_practice/data-type/enum/G.TYP.ENM.02.md) 109 | - [G.TYP.ENM.03 在使用类似 C 语言的枚举写法且使用repr(isize/usize) 布局时注意 32位架构上截断的问题](./safe-guides/coding_practice/data-type/enum/G.TYP.ENM.03.md) 110 | - [G.TYP.ENM.04 不宜在use语句中引入Enum的全部变体（variants）](./safe-guides/coding_practice/data-type/enum/G.TYP.ENM.04.md) 111 | - [G.TYP.ENM.05 对外导出的公开Enum，宜添加#[non_exhaustive]属性](./safe-guides/coding_practice/data-type/enum/G.TYP.ENM.05.md) 112 | - [G.TYP.ENM.06 Enum内变体的大小差异不宜过大](./safe-guides/coding_practice/data-type/enum/G.TYP.ENM.06.md) 113 | - [Express](./safe-guides/coding_practice/expr.md) 114 | - [G.EXP.01 当需要对表达式求值后重新赋值时，宜使用复合赋值模式](./safe-guides/coding_practice/expr/G.EXP.01.md) 115 | - [G.EXP.02 不宜在比较中使用不兼容的位掩码](./safe-guides/coding_practice/expr/G.EXP.02.md) 116 | - [G.EXP.03 不应利用数组表达式的边界检查来 Panic，而应使用断言](./safe-guides/coding_practice/expr/G.EXP.03.md) 117 | - [G.EXP.04 自增或自减运算使用`+=`或`-=`](./safe-guides/coding_practice/expr/G.EXP.04.md) 118 | - [G.EXP.05 使用括号来清楚表示表达式的计算顺序](./safe-guides/coding_practice/expr/G.EXP.05.md) 119 | - [G.EXP.06 避免在比较中添加无用的掩码操作](./safe-guides/coding_practice/expr/G.EXP.06.md) 120 | - [Control Flow](./safe-guides/coding_practice/control-flow.md) 121 | - [P.CTF.01 避免滥用迭代器](./safe-guides/coding_practice/control-flow/P.CTF.01.md) 122 | - [P.CTF.02 优先使用模式匹配而非判断后再取值](./safe-guides/coding_practice/control-flow/P.CTF.02.md) 123 | - [G.CTF.01 当需要通过多个if判断来比较大小来区分不同情况时，优先使用match和cmp来代替if表达式](./safe-guides/coding_practice/control-flow/G.CTF.01.md) 124 | - [G.CTF.02 if条件表达式分支中如果包含了else if分支也应该包含else分支](./safe-guides/coding_practice/control-flow/G.CTF.02.md) 125 | - [G.CTF.03 如果要通过 if 条件表达式来判断是否 Panic，请优先使用断言](./safe-guides/coding_practice/control-flow/G.CTF.03.md) 126 | - [G.CTF.04 在 Match 分支的 Guard 语句中不要使用带有副作用的条件表达式](./safe-guides/coding_practice/control-flow/G.CTF.04.md) 127 | - [String](./safe-guides/coding_practice/strings.md) 128 | - [P.STR.01 处理字符串元素时优先按字节处理而非字符](./safe-guides/coding_practice/strings/P.STR.01.md) 129 | - [P.STR.02 创建字符串时，宜预先分配大约足够的容量来避免后续操作中产生多次分配](./safe-guides/coding_practice/strings/P.STR.02.md) 130 | - [P.STR.03 在使用内建字符串处理函数或方法的时候，应注意避免隐藏的嵌套迭代或多次迭代](./safe-guides/coding_practice/strings/P.STR.03.md) 131 | - [P.STR.04 只在合适的场景下，使用正则表达式第三方库regex](./safe-guides/coding_practice/strings/P.STR.04.md) 132 | - [P.STR.05 在拼接字符串时，优先使用format!](./safe-guides/coding_practice/strings/P.STR.05.md) 133 | - [G.STR.01 在实现Display特质时不应调用to_string()方法](./safe-guides/coding_practice/strings/G.STR.01.md) 134 | - [G.STR.02 在追加字符串时使用push_str方法](./safe-guides/coding_practice/strings/G.STR.02.md) 135 | - [G.STR.03 将只包含 ASCII字符的字符串字面量转为字节序列可以直接使用b"str" 语法代替调用as_bytes方法](./safe-guides/coding_practice/strings/G.STR.03.md) 136 | - [G.STR.04 需要辨别字符串的字符开头或结尾字符时，不应按字符迭代比较](./safe-guides/coding_practice/strings/G.STR.04.md) 137 | - [G.STR.05 对字符串按指定位置进行切片的时候需要小心破坏其 UTF-8 编码](./safe-guides/coding_practice/strings/G.STR.05.md) 138 | - [Collections](./safe-guides/coding_practice/collections.md) 139 | - [P.CLT.01 创建HashMap、VecDeque时，可以预先分配大约足够的容量来避免后续操作中产生多次分配](./safe-guides/coding_practice/collections/P.CLT.01.md) 140 | - [G.CLT.01 非必要情况下，不要使用LinkedList，而用Vec或VecDeque代替](./safe-guides/coding_practice/collections/G.CLT.01.md) 141 | - [Function Design](./safe-guides/coding_practice/fn-design.md) 142 | - [P.FUD.01 Should rebind variables which pass into closure](./safe-guides/coding_practice/fn-design/P.FUD.01.md) 143 | - [P.FUD.02 Don't Use `return` for return value](./safe-guides/coding_practice/fn-design/P.FUD.02.md) 144 | - [G.FUD.01 Less than 5 function parameters](./safe-guides/coding_practice/fn-design/G.FUD.01.md) 145 | - [G.FUD.02 Should input as reference if parameter derives `Copy` and its value inputed by-value is a big number](./safe-guides/coding_practice/fn-design/G.FUD.02.md) 146 | - [G.FUD.03 Should refactor into customized `struct` or `enum` if there are too many `bool` type's function parameters](./safe-guides/coding_practice/fn-design/G.FUD.03.md) 147 | - [G.FUD.04 Should input by-value but by-ref if parameter derived `Copy`, and its value is a small enough number](./safe-guides/coding_practice/fn-design/G.FUD.04.md) 148 | - [G.FUD.05 Don't always specify `#[inline(always)]` for function](./safe-guides/coding_practice/fn-design/G.FUD.05.md) 149 | - [G.FUD.06 Parameters Should be compatible with multiple types](./safe-guides/coding_practice/fn-design/G.FUD.06.md) 150 | - [Generic](./safe-guides/coding_practice/generic.md) 151 | - [P.GEN.01 用泛型来抽象公共语义](./safe-guides/coding_practice/generic/P.GEN.01.md) 152 | - [P.GEN.02 不要随便使用 impl Trait 语法替代泛型限定](./safe-guides/coding_practice/generic/P.GEN.02.md) 153 | - [P.GEN.03 不要使用太多泛型参数和 trait 限定，否则会增长编译时间](./safe-guides/coding_practice/generic/P.GEN.03.md) 154 | - [P.GEN.04 为泛型类型实现方法时，impl 中声明的泛型类型参数一定要被用到](./safe-guides/coding_practice/generic/P.GEN.04.md) 155 | - [P.GEN.05 定义泛型函数时，如果该函数实现用到来自 trait 定义的相关行为，需要为泛型指定相关 trait 的限定](./safe-guides/coding_practice/generic/P.GEN.05.md) 156 | - [G.GEN.01 不要在泛型位置上使用内建类型](./safe-guides/coding_practice/generic/G.GEN.01.md) 157 | - [G.GEN.02 使用 Rust 标准库中某些方法，要注意避免使用其泛型默认实现，而应该使用具体类型的实现](./safe-guides/coding_practice/generic/G.GEN.02.md) 158 | - [Trait](./safe-guides/coding_practice/traits.md) 159 | - [P.TRA.01 使用 trait 时要注意 trait 一致性规则](./safe-guides/coding_practice/traits/P.TRA.01.md) 160 | - [标准库内置 trait](./safe-guides/coding_practice/traits/std-builtin.md) 161 | - [P.TRA.BLN.01 在实现Borrow特质时，需要注意一致性](./safe-guides/coding_practice/traits/std-builtin/P.TRA.BLN.01.md) 162 | - [G.TRA.BLN.01 应该具体类型的 default() 方法代替 Default::default() 调用](./safe-guides/coding_practice/traits/std-builtin/G.TRA.BLN.01.md) 163 | - [G.TRA.BLN.02 不要为迭代器实现Copy 特质](./safe-guides/coding_practice/traits/std-builtin/G.TRA.BLN.02.md) 164 | - [G.TRA.BLN.03 能使用派生宏（Derive）自动实现Default特质就不要用手工实现](./safe-guides/coding_practice/traits/std-builtin/G.TRA.BLN.03.md) 165 | - [G.TRA.BLN.04 在使用#[derive(Hash)] 的时候，避免再手工实现 PartialEq](./safe-guides/coding_practice/traits/std-builtin/G.TRA.BLN.04.md) 166 | - [G.TRA.BLN.05 在使用#[derive(Ord)] 的时候，避免再手工实现 PartialOrd](./safe-guides/coding_practice/traits/std-builtin/G.TRA.BLN.05.md) 167 | - [G.TRA.BLN.06 不要对实现 Copy 或引用类型调用 std::mem::drop 和 std::mem::forgot](./safe-guides/coding_practice/traits/std-builtin/G.TRA.BLN.06.md) 168 | - [G.TRA.BLN.07 对实现 Copy 的可迭代类型来说，要通过迭代器拷贝其所有元素时，应该使用 copied方法，而非cloned](./safe-guides/coding_practice/traits/std-builtin/G.TRA.BLN.07.md) 169 | - [G.TRA.BLN.08 实现 From 而不是 Into](./safe-guides/coding_practice/traits/std-builtin/G.TRA.BLN.08.md) 170 | - [G.TRA.BLN.09 一般情况下不要给 Copy 类型手工实现 Clone](./safe-guides/coding_practice/traits/std-builtin/G.TRA.BLN.09.md) 171 | - [G.TRA.BLN.10 不要随便使用Deref特质来模拟继承](./safe-guides/coding_practice/traits/std-builtin/G.TRA.BLN.10.md) 172 | - [trait 对象](./safe-guides/coding_practice/traits/trait-object.md) 173 | - [P.TRA.OBJ.01 根据场景合理选择使用trait对象或泛型静态分发](./safe-guides/coding_practice/traits/trait-object/P.TRA.OBJ.01.md) 174 | - [P.TRA.OBJ.02 除非必要，避免自定义虚表](./safe-guides/coding_practice/traits/trait-object/P.TRA.OBJ.02.md) 175 | - [Error Handling](./safe-guides/coding_practice/error-handle.md) 176 | - [P.ERR.01 当传入函数的参数值因为超出某种限制可能会导致函数调用失败，应该使用断言](./safe-guides/coding_practice/error-handle/P.ERR.01.md) 177 | - [P.ERR.02 在确定 Option 和 Result类型的值不可能是 None 或 Err 时，请用 expect 代替 unwrap()](./safe-guides/coding_practice/error-handle/P.ERR.02.md) 178 | - [G.ERR.01 在处理 Option 和 Result 类型时，不要随便使用 unwrap](./safe-guides/coding_practice/error-handle/G.ERR.01.md) 179 | - [G.ERR.02 不要滥用 expect，请考虑用 unwrap_or_ 系列方法代替](./safe-guides/coding_practice/error-handle/G.ERR.02.md) 180 | - [Memory Management](./safe-guides/coding_practice/memory.md) 181 | - [生命周期](./safe-guides/coding_practice/memory/lifetime.md) 182 | - [P.MEM.LFT.01 生命周期参数命名尽量有意义且简洁](./safe-guides/coding_practice/memory/lifetime/P.MEM.LFT.01.md) 183 | - [P.MEM.LFT.02 通常需要显式地标注生命周期，而非利用编译器推断](./safe-guides/coding_practice/memory/lifetime/P.MEM.LFT.02.md) 184 | - [智能指针](./safe-guides/coding_practice/memory/smart-ptr.md) 185 | - [P.MEM.SPT.01 使用 `RefCell` 时宜使用 `try_borrow`/`try_borrow_mut` 方法](./safe-guides/coding_practice/memory/smart-ptr/P.MEM.SPT.01.md) 186 | - [Box 类型](./safe-guides/coding_practice/memory/box.md) 187 | - [G.MEM.BOX.01 一般情况下，不应直接对 `Box` 进行借用](./safe-guides/coding_practice/memory/box/G.MEM.BOX.01.md) 188 | - [G.MEM.BOX.02 一般情况下，不应直接对已经在堆上分配内存的类型进行 Box 装箱](./safe-guides/coding_practice/memory/box/G.MEM.BOX.02.md) 189 | - [G.MEM.BOX.03 一般情况下，不应直接对栈分配类型进行 Box 装箱](./safe-guides/coding_practice/memory/box/G.MEM.BOX.03.md) 190 | - [Drop 析构](./safe-guides/coding_practice/memory/drop.md) 191 | - [G.MEM.DRP.01 要注意防范内存泄漏](./safe-guides/coding_practice/memory/drop/G.MEM.DRP.01.md) 192 | - [Module](./safe-guides/coding_practice/module.md) 193 | - [P.MOD.01 合理控制对外接口和模块之间的可见性](./safe-guides/coding_practice/module/P.MOD.01.md) 194 | - [P.MOD.02 将模块的测试移动到单独的文件，有助于增加编译速度](./safe-guides/coding_practice/module/P.MOD.02.md) 195 | - [G.MOD.01 使用导入模块中的类型或函数，在某些情况下需要带模块名前缀](./safe-guides/coding_practice/module/G.MOD.01.md) 196 | - [G.MOD.02 如果是作为库供别人使用，在 lib.rs中重新导出对外类型、函数和 trait 等](./safe-guides/coding_practice/module/G.MOD.02.md) 197 | - [G.MOD.03 导入模块不要随便使用 通配符`*`](./safe-guides/coding_practice/module/G.MOD.03.md) 198 | - [G.MOD.04 一个项目中应该避免使用不同的模块布局风格](./safe-guides/coding_practice/module/G.MOD.04.md) 199 | - [G.MOD.05 不要在私有模块中设置其内部类型或函数方法为 pub(crate)](./safe-guides/coding_practice/module/G.MOD.05.md) 200 | - [Package Management](./safe-guides/coding_practice/cargo.md) 201 | - [P.CAR.01 应该尽量把项目划分为合理的 crate 组合](./safe-guides/coding_practice/cargo/P.CAR.01.md) 202 | - [P.CAR.02 不要滥用 Features](./safe-guides/coding_practice/cargo/P.CAR.02.md) 203 | - [P.CAR.03 使用 cargo features 来代替 `--cfg` 条件编译参数](./safe-guides/coding_practice/cargo/P.CAR.03.md) 204 | - [P.CAR.04 如果可能的话，使用 `cfg!` 来代替 `#[cfg]`](./safe-guides/coding_practice/cargo/P.CAR.04.md) 205 | - [G.CAR.01 当项目是可执行程序而非库时，建议使用 `src/main.rs` 和 `src/lib.rs` 模式](./safe-guides/coding_practice/cargo/G.CAR.01.md) 206 | - [G.CAR.02 Crate 的 Cargo.toml 中应该包含必要的元信息](./safe-guides/coding_practice/cargo/G.CAR.02.md) 207 | - [G.CAR.03 Feature 命名应该避免否定式或多余的前后缀](./safe-guides/coding_practice/cargo/G.CAR.03.md) 208 | - [G.CAR.04 Cargo.toml 中依赖包版本不应使用通配符](./safe-guides/coding_practice/cargo/G.CAR.04.md) 209 | - [Macro](./safe-guides/coding_practice/macros.md) 210 | - [P.MAC.01 不要轻易使用宏](./safe-guides/coding_practice/macros/P.MAC.01.md) 211 | - [P.MAC.02 实现宏语法的时候，应该尽量贴近 Rust 语法](./safe-guides/coding_practice/macros/P.MAC.02.md) 212 | - [G.MAC.01 `dbg!()` 宏只应该用于调试代码](./safe-guides/coding_practice/macros/G.MAC.01.md) 213 | - [G.MAC.02 使用宏时应该考虑宏展开会让编译文件膨胀的影响](./safe-guides/coding_practice/macros/G.MAC.02.md) 214 | - [Declarative Macro](./safe-guides/coding_practice/macros/decl.md) 215 | - [P.MAC.DCL.01 不要将声明宏内的变量作为外部变量使用](./safe-guides/coding_practice/macros/decl/P.MAC.DCL.01.md) 216 | - [P.MAC.DCL.02 在编写多个宏规则时，应该先从匹配粒度最小的开始写](./safe-guides/coding_practice/macros/decl/P.MAC.DCL.02.md) 217 | - [P.MAC.DCL.03 不要在片段分类符跟随它不匹配的符号](./safe-guides/coding_practice/macros/decl/P.MAC.DCL.03.md) 218 | - [P.MAC.DCL.04 匹配规则要精准，不要模糊不清](./safe-guides/coding_practice/macros/decl/P.MAC.DCL.04.md) 219 | - [P.MAC.DCL.05 使用宏替换（substitution）元变量的时候要注意选择合适的片段分类符](./safe-guides/coding_practice/macros/decl/P.MAC.DCL.05.md) 220 | - [P.MAC.DCL.06 当宏需要接收 self 时需要注意](./safe-guides/coding_practice/macros/decl/P.MAC.DCL.06.md) 221 | - [P.MAC.DCL.07 确保在宏定义之后再去调用宏](./safe-guides/coding_practice/macros/decl/P.MAC.DCL.07.md) 222 | - [P.MAC.DCL.08 同一个 crate 内定义的宏相互调用时，需要注意卫生性](./safe-guides/coding_practice/macros/decl/P.MAC.DCL.08.md) 223 | - [Procedural Macro](./safe-guides/coding_practice/macros/proc.md) 224 | - [P.MAC.PRO.01 不要使用过程宏来规避静态分析检查](./safe-guides/coding_practice/macros/proc/P.MAC.PRO.01.md) 225 | - [P.MAC.PRO.02 实现过程宏时要对关键特性增加测试](./safe-guides/coding_practice/macros/proc/P.MAC.PRO.02.md) 226 | - [P.MAC.PRO.03 保证过程宏的卫生性](./safe-guides/coding_practice/macros/proc/P.MAC.PRO.03.md) 227 | - [P.MAC.PRO.04 给出正确的错误位置](./safe-guides/coding_practice/macros/proc/P.MAC.PRO.04.md) 228 | - [P.MAC.PRO.05 代码生成要按情况选择使用过程宏还是 `build.rs`](./safe-guides/coding_practice/macros/proc/P.MAC.PRO.05.md) 229 | - [P.MAC.PRO.06 `build.rs` 生成的代码要保证没有任何警告](./safe-guides/coding_practice/macros/proc/P.MAC.PRO.06.md) 230 | - [Multi Threads](./safe-guides/coding_practice/threads.md) 231 | - [Lock](./safe-guides/coding_practice/threads/lock.md) 232 | - [P.MTH.LCK.01 多线程下要注意识别锁争用的情况，避免死锁](./safe-guides/coding_practice/threads/lock/P.MTH.LCK.01.md) 233 | - [G.MTH.LCK.01 对布尔或引用并发访问应该使用原子类型而非互斥锁](./safe-guides/coding_practice/threads/lock/G.MTH.LCK.01.md) 234 | - [G.MTH.LCK.02 宜使用 Arc / Arc<[T]> 来代替 Arc / Arc>](./safe-guides/coding_practice/threads/lock/G.MTH.LCK.02.md) 235 | - [G.MTH.LCK.03 尽量避免直接使用标准库 `std::sync` 模块中的同步原语，替换为 `parking_lot`](./safe-guides/coding_practice/threads/lock/G.MTH.LCK.03.md) 236 | - [G.MTH.LCK.04 尽量避免直接使用标准库 `std::sync::mpsc` 模块中的 channel，替换为 `crossbeam`](./safe-guides/coding_practice/threads/lock/G.MTH.LCK.04.md) 237 | - [Lock Free](./safe-guides/coding_practice/threads/lock-free.md) 238 | - [P.MTH.LKF.01 除非必要，否则建议使用同步锁](./safe-guides/coding_practice/threads/lock-free/P.MTH.LKF.01.md) 239 | - [P.MTH.LKF.02 使用无锁编程时，需要合理选择内存顺序](./safe-guides/coding_practice/threads/lock-free/P.MTH.LKF.02.md) 240 | - [Async](./safe-guides/coding_practice/async-await.md) 241 | - [P.ASY.01 异步编程并不适合所有场景，计算密集型场景应该考虑同步编程](./safe-guides/coding_practice/async-await/P.ASY.01.md) 242 | - [G.ASY.01 在 `async` 块或函数中调用 `async` 函数或闭包请不要忘记添加`.await`](./safe-guides/coding_practice/async-await/G.ASY.01.md) 243 | - [G.ASY.02 在跨 await 调用中，需要对其持有的同步互斥锁进行处理](./safe-guides/coding_practice/async-await/G.ASY.02.md) 244 | - [G.ASY.03 在跨 await 调用中，需要对其持有 RefCell 的引用进行处理](./safe-guides/coding_practice/async-await/G.ASY.03.md) 245 | - [G.ASY.04 避免定义不必要的异步函数](./safe-guides/coding_practice/async-await/G.ASY.04.md) 246 | - [G.ASY.05 避免在异步处理过程中包含阻塞操作](./safe-guides/coding_practice/async-await/G.ASY.05.md) 247 | - [Unsafe Rust](./safe-guides/coding_practice/unsafe_rust.md) 248 | - [P.UNS.01 不要为了逃避编译器安全检查而滥用 Unsafe Rust](./safe-guides/coding_practice/unsafe_rust/P.UNS.01.md) 249 | - [P.UNS.02 不要为了提升性能而盲目使用 Unsafe Rust](./safe-guides/coding_practice/unsafe_rust/P.UNS.02.md) 250 | - [G.UNS.01 不宜为带有 unsafe 命名的类型或方法创建别名](./safe-guides/coding_practice/unsafe_rust/G.UNS.01.md) 251 | - [Safety Abstract](./safe-guides/coding_practice/unsafe_rust/safe_abstract.md) 252 | - [P.UNS.SAS.01 代码中要注意是否会因为 Panic 发生而导致内存安全问题](./safe-guides/coding_practice/unsafe_rust/safe_abstract/P.UNS.SAS.01.md) 253 | - [P.UNS.SAS.02 Unsafe 代码编写者有义务检查代码是否满足安全不变式](./safe-guides/coding_practice/unsafe_rust/safe_abstract/P.UNS.SAS.02.md) 254 | - [P.UNS.SAS.03 不要随便在公开的 API 中暴露未初始化内存](./safe-guides/coding_practice/unsafe_rust/safe_abstract/P.UNS.SAS.03.md) 255 | - [P.UNS.SAS.04 避免因为 Panic Safety 而导致双重释放](./safe-guides/coding_practice/unsafe_rust/safe_abstract/P.UNS.SAS.04.md) 256 | - [P.UNS.SAS.05 手动实现 auto trait 时要充分考虑其安全性](./safe-guides/coding_practice/unsafe_rust/safe_abstract/P.UNS.SAS.05.md) 257 | - [P.UNS.SAS.06 不要随便在公开的 API 中暴露裸指针](./safe-guides/coding_practice/unsafe_rust/safe_abstract/P.UNS.SAS.06.md) 258 | - [P.UNS.SAS.07 在抽象安全方法的同时，也建议为性能考虑而增加相应的 Unsafe 方法](./safe-guides/coding_practice/unsafe_rust/safe_abstract/P.UNS.SAS.07.md) 259 | - [P.UNS.SAS.08 函数参数是不可变借用的时候，返回值不应该是可变借用](./safe-guides/coding_practice/unsafe_rust/safe_abstract/P.UNS.SAS.08.md) 260 | - [P.UNS.SAS.09 在任何 Unsafe 块之前都应该加 SAFETY 注释](./safe-guides/coding_practice/unsafe_rust/safe_abstract/P.UNS.SAS.09.md) 261 | - [G.UNS.SAS.01 在公开的 unsafe 函数的文档中必须增加 Safety 注释](./safe-guides/coding_practice/unsafe_rust/safe_abstract/G.UNS.SAS.01.md) 262 | - [G.UNS.SAS.02 在 Unafe 函数中应使用 `assert!` 而非 `debug_assert!` 去校验边界条件](./safe-guides/coding_practice/unsafe_rust/safe_abstract/G.UNS.SAS.02.md) 263 | - [Modification of Raw Pointer](./safe-guides/coding_practice/unsafe_rust/raw_ptr.md) 264 | - [P.UNS.PTR.01 不要将裸指针在多线程间共享](./safe-guides/coding_practice/unsafe_rust/raw_ptr/P.UNS.PTR.01.md) 265 | - [P.UNS.PTR.02 建议使用 `NonNull` 来替代 `*mut T`](./safe-guides/coding_practice/unsafe_rust/raw_ptr/P.UNS.PTR.02.md) 266 | - [P.UNS.PTR.03 使用指针类型构造泛型结构体时，需要使用 `PhantomData` 来指定 `T`上的协变和所有权](./safe-guides/coding_practice/unsafe_rust/raw_ptr/P.UNS.PTR.03.md) 267 | - [G.UNS.PTR.01 当指针类型被强转为和当前内存对齐不一致的指针类型时，禁止对其解引用](./safe-guides/coding_practice/unsafe_rust/raw_ptr/G.UNS.PTR.01.md) 268 | - [G.UNS.PTR.02 禁止将不可变指针手工转换为可变指针](./safe-guides/coding_practice/unsafe_rust/raw_ptr/G.UNS.PTR.02.md) 269 | - [G.UNS.PTR.03 尽量使用 `pointer::cast` 来代替 使用 `as` 强转指针](./safe-guides/coding_practice/unsafe_rust/raw_ptr/G.UNS.PTR.03.md) 270 | - [Union](./safe-guides/coding_practice/unsafe_rust/union.md) 271 | - [P.UNS.UNI.01 除了与 C 交互，尽量不要使用 Union](./safe-guides/coding_practice/unsafe_rust/union/P.UNS.UNI.01.md) 272 | - [P.UNS.UNI.02 不要把联合体的不同变体用在不同生命周期内](./safe-guides/coding_practice/unsafe_rust/union/P.UNS.UNI.02.md) 273 | - [Memory](./safe-guides/coding_practice/unsafe_rust/mem.md) 274 | - [P.UNS.MEM.01 要注意选择合适的结构体、元组、枚举的数据布局](./safe-guides/coding_practice/unsafe_rust/mem/P.UNS.MEM.01.md) 275 | - [P.UNS.MEM.02 不能修改其它进程或动态库的内存变量](./safe-guides/coding_practice/unsafe_rust/mem/P.UNS.MEM.02.md) 276 | - [P.UNS.MEM.03 不能让 `String/Vec` 自动 Drop 其它进程或动态库的内存数据](./safe-guides/coding_practice/unsafe_rust/mem/P.UNS.MEM.03.md) 277 | - [P.UNS.MEM.04 尽量用可重入(reentrant)版本的 C-API 或系统调用](./safe-guides/coding_practice/unsafe_rust/mem/P.UNS.MEM.04.md) 278 | - [P.UNS.MEM.05 如果需要使用位域，推荐使用第三方库](./safe-guides/coding_practice/unsafe_rust/mem/P.UNS.MEM.05.md) 279 | - [G.UNS.MEM.01 使用 `MaybeUninit` 来处理未初始化的内存](./safe-guides/coding_practice/unsafe_rust/mem/G.UNS.MEM.01.md) 280 | - [FFi](./safe-guides/coding_practice/unsafe_rust/ffi.md) 281 | - [P.UNS.FFI.01 避免从公开的 Rust API 直接传字符串到 C 中](./safe-guides/coding_practice/unsafe_rust/ffi/P.UNS.FFI.01.md) 282 | - [P.UNS.FFI.02 在使用标准库 `std::ffi` 模块提供的类型时需要仔细查看其文档](./safe-guides/coding_practice/unsafe_rust/ffi/P.UNS.FFI.02.md) 283 | - [P.UNS.FFI.03 当使用来自 C 的指针时，如果该指针需要管理内存，则需要为包装该指针的 Rust 类型实现 Drop 特质](./safe-guides/coding_practice/unsafe_rust/ffi/P.UNS.FFI.03.md) 284 | - [P.UNS.FFI.04 如果一个函数正在跨越 FFi 边界，那么需要处理 Panic](./safe-guides/coding_practice/unsafe_rust/ffi/P.UNS.FFI.04.md) 285 | - [P.UNS.FFI.05 建议使用诸如标准库或 `libc` crate 所提供的可移植类型别名，而不是特定平台的类型](./safe-guides/coding_practice/unsafe_rust/ffi/P.UNS.FFI.05.md) 286 | - [P.UNS.FFI.06 Rust 和 C 之间传递字符或字符串时需要注意字符串要符合 C-ABI 以及 字符串的编码](./safe-guides/coding_practice/unsafe_rust/ffi/P.UNS.FFI.06.md) 287 | - [P.UNS.FFI.07 不要为任何传出外部的类型实现 Drop](./safe-guides/coding_practice/unsafe_rust/ffi/P.UNS.FFI.07.md) 288 | - [P.UNS.FFI.08 FFi 中要进行合理的错误处理](./safe-guides/coding_practice/unsafe_rust/ffi/P.UNS.FFI.08.md) 289 | - [P.UNS.FFI.09 当 Rust 调用外部 C 函数时，如果可以确认安全，可以通过引用来代替裸指针](./safe-guides/coding_practice/unsafe_rust/ffi/P.UNS.FFI.09.md) 290 | - [P.UNS.FFI.10 当 Rust 函数导出外部函数时，必须从设计上保证被跨线程调用的安全性](./safe-guides/coding_practice/unsafe_rust/ffi/P.UNS.FFI.10.md) 291 | - [P.UNS.FFI.11 如需引用指定为 `#[repr(packed)]` 内存布局的结构体成员字段要注意合理规避未定义行为](./safe-guides/coding_practice/unsafe_rust/ffi/P.UNS.FFI.11.md) 292 | - [P.UNS.FFI.12 当依赖 C 端传入参数时，需要在文档注释中不变性声明，根据不同的调用场景选择合适的安全抽象方式](./safe-guides/coding_practice/unsafe_rust/ffi/P.UNS.FFI.12.md) 293 | - [P.UNS.FFI.13 自定义数据类型要保证一致的数据布局](./safe-guides/coding_practice/unsafe_rust/ffi/P.UNS.FFI.13.md) 294 | - [P.UNS.FFI.14 在 FFi 中使用的类型应该拥有稳定布局](./safe-guides/coding_practice/unsafe_rust/ffi/P.UNS.FFI.14.md) 295 | - [P.UNS.FFI.15 从外部传入的不健壮类型的外部值要进行检查](./safe-guides/coding_practice/unsafe_rust/ffi/P.UNS.FFI.15.md) 296 | - [I/O](./safe-guides/coding_practice/unsafe_rust/io.md) 297 | - [P.UNS.FIO.01 在使用原始句柄的时候，要注意 `I/O` 安全性](./safe-guides/coding_practice/unsafe_rust/io/P.UNS.FIO.01.md) 298 | - [Unsafe 代码术语指南](./safe-guides/coding_practice/unsafe_rust/glossary.md) 299 | - [no-std](./safe-guides/coding_practice/no-std.md) 300 | - [P.EMB.01 no-std 下必须定义一个Panic行为以确保安全](./safe-guides/coding_practice/no-std/P.EMB.01.md) 301 | - [P.EMB.02 no-std 下要确保程序中的类型有正确的内存布局](./safe-guides/coding_practice/no-std/P.EMB.02.md) 302 | - [I/O](./safe-guides/coding_practice/io.md) 303 | - [P.FIO.01 使用 `read_to_end`/`read_to_string`方法时注意文件的大小能否一次性读入内存中](./safe-guides/coding_practice/io/P.FIO.01.md) 304 | - [G.FIO.01 文件读取建议使用 `BufReader`/`BufWriter` 来代替 `Reader`/`Write`](./safe-guides/coding_practice/io/G.FIO.01.md) 305 | - [Information Security](./safe-guides/coding_practice/security.md) 306 | - [P.SEC.01 使用第三方库的时候要确保可信的依赖，小心供应链攻击](./safe-guides/coding_practice/security/P.SEC.01.md) 307 | - [G.SEC.01 代码中不要出现非法 Unicode 字符，也要防范非法 Unicode 字符](./safe-guides/coding_practice/security/G.SEC.01.md) 308 | - [Others](./safe-guides/coding_practice/others.md) 309 | - [G.OTH.01 对于某些场景下不建议使用的方法可以通过配置 clippy.toml 来拒绝](./safe-guides/coding_practice/others/G.OTH.01.md) 310 | - [G.OTH.01 使用标准库中对应的方法计算秒级、毫秒级、微秒级的时间](./safe-guides/coding_practice/others/G.OTH.02.md) 311 | - [Appendix](./safe-guides/Appendix/toc.md) 312 | - [A.Development Enviroment](./safe-guides/Appendix/dev_env.md) 313 | - [B.Test](./safe-guides/Appendix/test.md) 314 | - [Unit Test](./safe-guides/Appendix/test/unit_test.md) 315 | - [Benchmark Test](./safe-guides/Appendix/test/benchmark.md) 316 | - [Fuzz Test](./safe-guides/Appendix/test/fuzz.md) 317 | - [C.Terminology](./safe-guides/Appendix/terms.md) 318 | - [D.Templates](./safe-guides/Appendix/templates/intro.md) 319 | - [rustfmt](./safe-guides/Appendix/templates/rustfmt.toml.md) 320 | - [clippy](./safe-guides/Appendix/templates/clippy.toml.md) 321 | - [deny](./safe-guides/Appendix/templates/deny.toml.md) 322 | - [E.Toolchains](./safe-guides/Appendix/tools/intro.md) 323 | - [rustfmt](./safe-guides/Appendix/tools/rustfmt.md) 324 | - [noisy-clippy](./safe-guides/Appendix/tools/noisy-clippy.md) 325 | - [cargo-udeps](./safe-guides/Appendix/tools/cargo-udeps.md) 326 | - [F.Cheat Sheet](./safe-guides/Appendix/cheat-sheet/README.md) 327 | - [Float](./safe-guides/Appendix/cheat-sheet/Numbers/float.md) 328 | - [G.Guide for Optimizations](./safe-guides/Appendix/optimizing/intro.md) 329 | - [H.Rustc Flags](./safe-guides/Appendix/rustc-flag.md) 330 | - [I.Best Practice](./safe-guides/Appendix/best-practice/intro.md) 331 | - [FAQ for Beginners](./safe-guides/Appendix/best-practice/qa.md) 332 | - [Rust Programming Techniques](./safe-guides/Appendix/best-practice/tips.md) 333 | - [J.Contribution Guidlines](./safe-guides/Appendix/contribution.md) 334 | 335 | 336 | 337 | 338 | 339 | 340 | 341 | 342 | 343 | 344 | 345 | 346 | --------------------------------------------------------------------------------