1.4 条款组织方式
每个条款一般包含标题、级别、描述等组成部分
规范条款分为原则和规则两个类别:
- 原则: 可以评价规则内容制定的好坏并引导规则进行相应的调整(从规范架构和功能上说,指导规 则的制定以及代码/框架/功能的设计)。工具不检测原则类条目。
- 规则: 是需要遵从或参考的实践。工具会检测规则类条目。
标题
概括本条款的要求或建议。
通过标题前的编号标识出条款的类别为原则或规则:其中'P'为单词Principle首字母, 'G'为单词 Guideline的首字母。
- 标识
P
为原则。编号方式为P.Element.Number
。 - 标识
G
为规则。编号方式为G.Element.Number
。 - 当有子目录时,编号方式为
P.Element.SubElement.Number
或G.Element.SubElement.Number
。 其中Element
为领域知识中关键元素(本规范中对应的二级目录)的 3 英文字母缩略语。Number
是 从 1 开始递增的两位阿拉伯数字,不足两位时高位补 0。
(术语参考: SEI CERT C Coding Standard )
Element | 解释 | Element | 解释 |
---|---|---|---|
NAM | 命名 (Naming) | CMT | 注释 (Comment) |
FMT | 格式 (Format) | TYP | 数据类型 (Data Type) |
CNS | 常量 (Const) | PTR | 指针 (Pointer) |
EXP | 表达式 (Expression) | CTF | 控制流程 (Control Flow) |
STR | 字符串 (String) | INT | 整数 (Integer) |
MOD | 模块 (Module) | MEM | 内存 (Memory) |
MAC | 宏 (Macro) | FUD | 函数设计 (Function Design) |
ASY | 异步 (Async) | TRA | Trait |
ERR | 错误处理 (Error Handle) | UNS | 非安全 (Unsafe Rust) |
MTH | 多线程 (Multi Threads) | FFI | 外部函数调用接口 ( Foreign Function Interface ) |
SLC | 切片类型 (Slice) | BOL | 布尔 (Bool) |
CHR | 字符类型 (Char) | FLT | 浮点数 (Float) |
SCT | 结构体 (Struct) | SAF | 内存安全 (Safety) |
DCL | 声明宏 (Declarative) | PRO | 过程宏 (Procedural) |
级别 规则类条款分为两个级别:
- 要求:表示产品原则上应该遵从,但可以按照具体产品版本计划和节奏分期实现
- 建议:表示该条款属于优秀的编程实践,有助于进一步消解风险,产品可结合业务情况考虑是否纳 入,但要保证实施一致的代码风格
描述
对条款的进一步描述,描述条款的原理,配合正确和错误的代码例子作为示范。有的条款还包含一些规 则不适用的例外场景。
说明
对条款中的名词、背景、原理等进行补充说明。