Rust 编码风格指南
Rust 编码风格指南
“冲突”指的是本风格指南提出的建议模式与 Rust 官方风格指南中主要鼓励的模式相悖,或属于后者不推荐的情况。
为什么本指南的指导原则会偏离常规的 Rust 风格规则?
大多数风格指南都有三个目标:一致性、可读性以及鼓励良好的 API 设计。无论具体选择如何,提前确定这些选择都有助于减少团队在琐事上的争论(bikeshedding)。
本风格指南同样追求上述目标,但它还有一个不常被提及的额外目标:为大规模变更(Large-Scale Changes, LSCs)铺平道路。像 Google 内部的许多大型代码库一样,有时需要借助工具运行跨越整个代码库的重构。为了让重构顺利进行,代码必须易于工具处理。一致性有助于实现这一点,但采用刻意设计的、对重构友好的代码模式同样重要。
在具体上下文中应用 API 设计规则
在应用与 API 设计相关的规则时,应区分两类代码:
-
库代码
- 供其他项目(应用或其他库)使用。
- 解决相对通用的问题。
-
应用代码
- 供单一应用程序使用。
- 解决更具体的问题。
对于库代码,涉及 API 设计的风格指南规则具有约束力。
对于应用代码,API 设计规则属于强烈建议。在应用这些规则时,请记住,由于应用代码旨在解决特定问题,它通常应优先考虑简洁性和直接性,而非广泛的通用性。避免过早的泛化和抽象,聚焦于满足当前需求所必需的内容。
代码组织
术语定义:
-
Crate是编译单位。一个 Crate 始终包含一个无名的 Rust 模块,即“根模块”。
-
Rust 模块是 Crate 内部的代码组织单位。Rust 模块用于控制名称的可见性。模块可以嵌套,也可以用于将代码拆分到不同的文件和目录中。
以下章节说明,在 Chromium 项目中,不建议充分利用将模块拆分到不同文件的所有可能性。
优先使用小 Crate [chrome]
使用扁平文件布局存放 rust_library 源码 [chrome]
rust_library 源码 [chrome]在 Chromium 中,属于同一个 rust_library(即一个 Rust crate)的 .rs 源文件必须位于同一个目录下。
不要使用子目录来组织属于同一个 crate 的文件。如果你觉得有必要将某个 crate 的文件放入子目录中组织,这通常意味着该 crate 已经过大,应当拆分。
这种 crate 布局刻意不同于开源仓库中常见的 Cargo 目录结构。
例外:位于 //third_party 下且同时使用 Cargo 构建的 Rust 代码,应当遵循标准的 Cargo 目录结构。
理由
Chromium 中这种做法由以下因素驱动:
- 基于对小型 crate 的偏好,大多数
rust_library目标只包含一个源文件。 - 正因如此,如果为每个
rust_library目标都建一个目录,会导致绝大多数目录里只有一个源文件。 - 多文件的
rust_library目标也不应为子模块单独建目录,以保证做法一致。
源文件和叶子模块以主要的用户自定义项命名
当一个 叶子模块 有主要的用户自定义项(如 Foo)时,模块应以该命名(如 mod foo 和 foo.rs)。
不属于某个特定抽象的叶子模块可以自行命名。
理由
这样可以一眼看出源文件或叶子模块的内容和用途。
不要在非叶子模块中实现 API
非叶子模块中只能包含模块声明(而非定义)和 re-exports。
注意,叶子模块 的定义允许包含以下子模块:mod test 以及跨语言绑定模块(如 #[cxx::bridge])。
例外:
- 在非叶子模块中放少量起"粘合作用"的核心实现代码是可以的,关键在于这类模块不要放太多代码。
理由
这样更容易查找代码,也避免了结构和内容混在一起。
不要使用 glob 导入
不要使用 glob 导入,以下几种情况可自行酌情选择:
- 内联模块中使用
use super::* - enum 的方法体中,以及主要处理该 enum 的函数中使用
use enum::* - 非叶子模块中使用
pub use submodule::* -
C++ 互操作:由于同一个命名空间(C++ 中)会对应不同 Rust crate 中的子模块,可以用 glob 导入把这些命名空间合并到一个私有副本中。例如:
mod absl { pub use status::absl::*; pub use strings::absl::*; }在这个假设的例子中,你可以像在 C++ 中一样,直接从 Rust 中使用
absl::Status和absl::StrCat,而不必写成status::absl::Status和strings::absl::StrCat。这种用法仅限于合并 C++ 命名空间,且合并后的模块不得对外公开。
如果使用鼓励使用 prelude(预导入模块)的第三方 crate,是否允许由代码审查者酌情决定。
这也意味着应避免定义 prelude。
理由
全局导入(Glob imports)会增加执行 LSC(Larger Clang Clang?此处指 Lint 类检查工具)的代码清理人员的负担,在没有交叉引用(xrefs)的环境下,也难以判断类型来源。
use 语句应只从单个模块导入项目
该规则对应 rustfmt 配置 imports_granularity = Module。
基本上,use 语句的 {..} 块内不应包含 ::。例如:
use foo::Foo;
use foo::bar::Bar;
use foo::bar::Baz;
use foo::Foo;
use foo::bar::{Bar, Baz};
use foo::{Foo, bar::Bar};
优先使用局部作用域的 trait 导入
除非 trait 的方法在整个文件中被广泛使用,否则应在函数体内导入 trait。
fn foo(x: u8) {
// 在函数内导入 trait,而非模块作用域。
use std::str::FromStr;
let string: String = x.parse();
}
使用模块名限定顶层函数调用
若要使用其他模块或 crate 中定义的顶层函数,请导入其模块,并通过 modulename::functionname() 形式调用。例如:
use std::mem;
let x = mem::transmute(y);
use std::mem::transmute;
let x = transmute(y);
例外情况:
- 导入名称足够明确、无歧义的函数,例如来自 C++ 的函数(C++ 中通常直接调用顶层自由函数)。
-
在 Chromium 中,从小型、单一用途的第一方 crate 导入函数时。
- 当模块名本身容易冲突时。例如,模块名是 C++ 命名空间名,且多个 crate 定义了相同的子模块。
理由
许多 Rust 代码库始终保持一致的风格约定:未限定的小写名称默认视为局部变量,因此可以认为 foo() 来自当前模块。这条规则主要是为了避免评审过程中的分歧,其好处主要在于保持代码风格一致,并有助于在无需交叉引用(xref)的情况下理解代码。
类型名称应导入后使用,无需限定路径
默认情况下,引用类型和 trait 时应省略模块路径。例如,代码应使用 Regex 而非 regex::Regex,并在文件头部或相关函数内部添加 use regex::Regex。
例外情况:
- 存在命名冲突时,可以直接引用常用名称的类型(如
io::Error)。也可以通过重命名来解决(如use std::io::Error as IoError)。 - 当涉及大型类型“组”时,例如
rustc 中的 hir 模块,其中包含大量 HIR 类型。 - 在宏和生成代码中,强制要求
use导入往往适得其反。 - 在依赖项较多的代码中,导入所有项会导致导入块过大,收益甚微。
理由
这条规则主要是为了避免评审过程中的分歧。
使用合适的导入机制 [chrome]
- 在 Chrome 中,使用
chromium::import!()。
代码格式与美观性
使用合适的格式化工具
使用合适的格式化工具(例如 Chromium 中的 git cl format)。
配置(面向风格指南作者)
如果代码库关心在 stable 版本上构建,且某些选项在当前的 stable Rust 中不可用,可以选择不应用以下 rustfmt 选项:
-
每行最大 100 列:
max_width = 100 -
十六进制字面量中使用小写字母(如
0xab123cdef而非0xAB123CDEF):hex_literal_case = Lower
宏匹配器的格式化:
format_macro_matchers = true
在字面量中对不可见字符使用转义。例如,如果文本中需要包含零宽连接符,应使用 \u{200D}。
退出自动格式化
你可以用 #[rustfmt::skip] 跳过自动格式化,但仅限于以下情况:
- 手动对齐——如果有特定场景需要代码以特定方式对齐(例如,多行相似的代码为了可读性希望保持对齐,或是构造矩阵的函数)。
- 生成的代码(理想情况下应改用 genrule)。
重要:不要因为个人风格偏好而跳过格式化。
所有权与借用
避免使用 Rc 和 Arc
管理内存时,应优先使用独占所有权和借用,而不是 Rc 和 Arc。
例外:
- 当其他所有权和借用结构在编写、理解或维护上复杂得不合理时,可以使用
Rc和Arc。这属于主观判断,应在代码评审中讨论决定。
理由
通常情况下,Rust 无需共享所有权智能指针就能表示对象图。这类指针会带来运行时开销和额外的复杂性。从其他语言转过来的工程师容易过早地使用 Rc 和 Arc。
优先使用借用而非深拷贝
只在真正需要对象深拷贝时才使用 .clone()。
不要用 .clone() 来代替借用。代码设计应自然符合 Rust 的所有权和借用规则。不过,如果借用关系变得过于复杂,.clone() 也不失为一种务实的选择。
在克隆与借用之间做选择时,需考虑代码的性能需求。
注意:这条建议不适用于克隆 Rc 或 Arc 指针。克隆引用计数指针并不会产生深拷贝,这是它们的预期用法。
理由
深拷贝涉及内存分配和数据复制,开销可能很大。
函数输入与输出
为不可变数据接受灵活的引用
当函数接受借用且不可变的数据时,应使用灵活性最高的引用类型。直接传递对数据的引用,而不是传递对智能指针、容器或包装器的引用。
| 使用 | 替代 | 原因 |
|---|---|---|
&T |
&Box<T> |
借用 Box 内部的数据 |
&[T] |
&Vec<T> |
接受任意切片,而非特定容器 |
&str |
&String |
接受字符串切片,而非对拥有型字符串的引用 |
Option<&T> |
&Option<T> |
借用 Option 内部的数据 |
例外情况:
- 当预期处理非线性字符数据(如 Rope/Cord)时。
作为背景参考,请查看 Clippy 的 lints
borrowed_box
和
ptr_arg。
依据
接受不提及具体智能指针、容器或包装器的引用类型,能使函数更具通用性和高性能:调用者可以以多种方式持有数据并直接传递,而无需先进行拷贝。
返回类型中迭代器与拥有型集合
尽可能优先返回迭代器(具体类型或 impl Iterator),而不是返回 Vec<T>。
注意:在应用代码中,如果返回 Vec<T> 能简化代码,且迭代器的灵活性和性能优势并非明显必需,那么返回 Vec 也是没问题的。
例外情况:
- 大多数调用者都需要构建一个拥有型 vector。
- 函数的实现本身自然地构建了 vector。
- 返回的值很可能需要进行随机索引访问。
- 算法作为
for循环运行效果更好,且强制分配带来的开销不重要。 - 函数的预期目的就是创建一个新的拥有型集合。
- 函数返回的是一个已存在的 vector。
依据
高复用性的库代码通常应致力于提供更灵活、性能更优的 API。返回迭代器能调用者自行决定如何消费数据:收集到 vector、在循环中处理,或串联更多迭代器适配器。其中部分选项可让用户避免不必要的内存分配。
而在应用代码中,函数的使用模式往往更易预测。若明确性能不是瓶颈,或数据最终本就会收集为 vector,返回 vector 反而能简化 API。
函数参数中:迭代器 vs. 切片
高复用性的库代码若仅需遍历输入,应接受迭代器或 impl IntoIterator。
注意:应用代码中,若接受切片 &[T] 能简化代码,且无需迭代器带来的灵活性与性能优势,则完全可行。
理由
高复用性的库代码通常应致力于提供更灵活、性能更优的 API。接受迭代器的函数为调用者带来:
- 更高的灵活性(数据可来自任意集合)
- 更高的效率(无需将数据拷贝到连续内存块)
- 更好的可组合性(函数与迭代器链条配合更顺畅)
而在应用代码中,函数的使用模式往往更易预测。若明确性能不是瓶颈,或调用方手中本就都是 vector,接受切片反而能简化 API。
接受 Into
设计接受 T 的库 API 时,若用户侧可能存在多种类型,且调用点的人体工学体验优先,应考虑接受 impl Into<T> 而非 T。
提示:需与代码膨胀的顾虑保持平衡;并非要求代码中大量使用 Into<T>。
注意:应用代码几乎不应使用 impl Into<T> 参数。
理由
使用 impl Into<T> 可使函数直接接受多种兼容类型的参数。例如,接受 impl Into<String> 的函数,调用时可直接传入 String 或 &str 字面量。
这里的权衡在于:在调用处省去一个 .into() 带来的便利,与使用泛型的代价(API 签名更复杂、代码体积增大,有时还会造成类型推断困难)之间如何取舍。
API 中优先使用 enum 而非 bool
当参数的含义不够一目了然时,函数参数应使用 enum 而不是 bool。
如果确实要用 bool,建议在参数列表中加行内注释,说明这个布尔值的用途。
错误报告
根据 API 的契约选择合适的错误报告机制:Option、Result 或 panic!。
简单的失败用 Option:失败原因显而易见,调用方不需要更多细节。这种方式最适合标准的、预期之中的结果,比如值缺失或解析不匹配。
// 好:失败原因显而易见(整数溢出),无法再提供更多有效细节。
fn checked_add(a: u32, b: u32) -> Option<u32> { ... }
可恢复且调用方需要上下文信息的失败用 Result。这类错误往往由外部因素(如 I/O 或网络)导致,属于"不可避免"的错误——即使代码写得再正确,也无法靠提前检查来防范。不过调用方可以合理预见错误的类型(文件相关函数可能因 I/O 错误而失败)。错误细节让调用方能够区分不同的失败模式,并做出恰当的恢复处理。
// 好:调用方需要知道失败的原因(是 NotFound 还是 PermissionDenied)。
fn open_file(path: &Path) -> Result<File, io::Error> { ... }
panic! 用于报告 bug 和被破坏的不变量。这类错误本可以避免:程序缺少某项检查,在前提条件不满足的情况下调用了某个操作。这类缺陷应当在代码中修复,而不是在运行时处理,尽管可以通过 catch_unwind 做粗粒度的恢复。
// 推荐做法:当违反不变量(索引必须在有效范围内)时触发 panic。
// 这表明调用方的逻辑存在 Bug。
impl<T> MyVec<T> {
pub fn remove(&mut self, index: usize) -> T {
if index >= self.len() {
panic!("index out of bounds");
}
// ...
}
}
注:部分代码库可能选择完全避免使用 panic,甚至要求将违反不变量的情况也通过 Result 返回。
例外情况:
- 面向开发者的二进制程序可以使用 panic 处理非致命错误。
- 测试代码可以使用 panic 进行断言。
类型
Newtype 与类型别名
在以下情况下,应使用 newtype 而非类型别名:
- 所定义的类型具有显著的语义差异时。
- 该类型需要拥有独立的 API 接口时。
- 希望保留后续修改底层类型的灵活性时,尤其是当你无法控制该类型的所有使用场景时。
- 出于类型安全考虑,当不同类型容易被混淆时。例如,
Date类型可以使用 newtype 来区分内部计算中的Day、Month和Year数值。
优先使用具名字段而非元组和非 newtype 的元组结构体
优先使用具名字段类型的类型,而非元组。因为元组索引(.0、.1 等)很快会变得令人困惑。
例外情况:
- Newtype 元组结构体(即仅包含一个字段的元组结构体)。
- 非常局部的上下文,且几乎不可能产生混淆的情况。
Trait
在必要时添加 trait 实现
一般原则是:底层库代码应主动预判用户需求,而应用程序代码则应在需要时添加 trait 实现。
实现标准库中已知的 trait,而非自定义方法
如果某个方法的目的和行为与标准库中的某个 trait 相符,请实现该 trait。例如,对于 Foo,不要写 fn from_str(&str) -> Self,而应编写 impl FromStr for Foo。
为了提高可发现性,同时保留自定义方法和 trait 实现是可以接受的。
参考 Clippy lint
should_implement_trait
(trait 列表)。
尽可能使用 #[derive()]
如果可以用 #[derive()] 实现,应避免手动编写。
Generics 与 dyn Trait
在库中,函数参数优先使用泛型(T: Trait 或 impl Trait),而非 dyn Trait。
例外:
- 对代码体积敏感的场景。
理由
-
效率
- 额外的间接性:创建
dyn Trait需要设置 fat pointer,且每次调用 trait 函数都需要查 vtable。 - 如果函数接受
dyn Trait,编译器无法执行某些优化(例如内联 trait 函数调用),而若函数是泛型的则可以实现。
- 额外的间接性:创建
-
某些 trait 不支持
dyn。例如,如果 trait 包含泛型函数、没有self参数的关联函数,或返回Self的函数,则它不兼容dyn。
何时定义 trait,何时使用固有关联实现(inherent implementation)
仅在以下目的时定义 trait:
-
启用泛型编程(在泛型函数和类型的约束中使用
T: Trait)。 -
接受或返回
impl Trait或dyn Trait。 -
定义extension trait(另见 extension trait 部分的注意事项)。
在其他希望为某个类型实现功能的情况下,请使用固有关联实现(inherent implementation)。
不要仅为了组织代码而使用 trait。
Extension trait
extension trait 是一种为来自不同 crate 的类型添加方法的 trait。
扩展 trait 与其他 trait 的区别在于,它的唯一目的是给类型添加方法,不用于泛型(T: Trait、impl Trait)或动态分发(dyn Trait)。为了表明这一点,扩展 trait 的命名应带上 ~Ext 后缀(例如 ForeignTypeExt)。
一般来说,拥有原始类型的团队也应同时拥有对应的扩展 trait。
例外情况:
- 预期会被广泛知晓并能带来显著价值的扩展方法,例如在基础库或框架中。
注意:这条规则专门针对扩展 trait。定义一个 trait 作为输入 trait(如 DateLike)并为一批外部类型实现它,是相对常见的做法。
示例
extern crate foreign_crate;
use foreign_crate::ForeignType;
trait ForeignTypeExt {
fn additional_method(&self);
}
impl ForeignTypeExt for ForeignType {
fn additional_method(&self) { ... }
}
也可以为实现了某个外部 trait 的所有类型定义扩展 trait。这实际上等价于给外部 trait 添加默认方法:
extern crate foreign_crate;
use foreign_crate::ForeignTrait;
trait ForeignTraitExt {
fn additional_method(&self);
}
impl<T: ForeignTrait> ForeignTraitExt for T {
fn additional_method(&self) { ... }
}
理由
当扩展 trait 与被扩展的类型由同一个团队维护时,可以避免基础类型与扩展 trait 之间、或两个扩展 trait 之间的方法命名冲突。
重要 trait 的具体指导
-
含公开字段的类型:考虑实现所有子字段都实现了的 trait。
-
Error 类型:尽量实现
Copytrait。Copy类型更易于管理和传递,因为可以按值传递而无需转移所有权。若 error 必须包含非Copy的字段(如String),则无法实现。 -
Copy:只要能合理确定该类型未来仍会保持Copy,就应实现它。 -
Clone:大多数类型都应实现Clone,除非它们代表某种外部资源。 -
Default:如果类型实现了new()方法或具有默认状态,应实现该 trait。可参考 Clippy 的new_without_default检查规则了解上下文。 -
PartialEq/Eq:若希望用户使用==运算符,优先实现PartialEq而非Eq。实现Eq时需注意它还要求自反性(详情见 https://doc.rust-lang.org/std/cmp/trait.Eq.html)。 -
PartialOrd/Ord:若希望用户使用<或>运算符,优先实现PartialOrd而非Ord。实现Ord时需注意它要求全序关系(详情见 https://doc.rust-lang.org/std/cmp/trait.Ord.html)。 -
Map 键
- 如果某类型可能作为 Map 的键或用于缓存,应实现
Hash和Eq。 - 若该类型还具有明确的全序关系,则应实现
Ord(及其所需的依赖 trait)。
- 如果某类型可能作为 Map 的键或用于缓存,应实现
重要的 From 实现需配合显式构造方法
如果类型的某个重要 From 实现是其主要构造方式之一,需补充固有的 ::new()、::new_from_foo() 或 ::from_foo() 方法。
Options 结构体应实现 Default
所有字段均为公开且主要用作函数“选项集合”的结构体,应实现 Default。
理由
这样可以方便地使用结构体更新语法(Struct { a: 0, ..Default::default()})。
并发
处理毒锁
切勿尝试访问已中毒互斥锁的内部状态,无论使用场景多么诱人。
不要使用 async / .await [chrome]
在 Chromium 中不要使用 async / .await。
避免通过 Rust 标准库创建新线程 [Chrome]
在 Chromium 中,优先使用 sequence(序列)而非线程。
使用 fuchsia_sync::Mutex [Fuchsia]
使用 Fuchsia 的互斥锁类型,而非来自 std::sync 或 parking_lot 的互斥锁。
宏
在考虑如何表达 API 时,按以下优先级进行选择:
-
普通的 Rust 函数、类型、trait、对象和模块。(尽可能避免使用宏、代码生成和元编程)。
-
macro_rules!风格的宏。 -
其他代码生成策略(如
genrule)。 -
proc_macro宏。
若决定使用宏或代码生成,请权衡其收益与代价:
- IDE、代码搜索及其他开发工具在处理包含宏的代码时效果会打折扣。
- 宏可能形成语言的“方言”,增加工程师跨代码库协作的难度。
- 大规模变更的落地难度更高、成本更大。
理由说明
优先使用非宏特性:宏可能形成语言的“方言”,增加工程师跨代码库协作的难度。当读者看到宏的用法时,相比未使用宏的代码,他们能对那段代码做出的假设更少。宏比常规 Rust 代码更难编写正确。
使用 macro_rules! 进行简单代码生成:由于 Rust 宏作用于 AST(抽象语法树),相比于文本代码生成,其健壮性通常更高。
命名
方法命名
方法命名请遵循 Rust 标准库风格。另请参阅 Comprehensive Rust 课程中关于 命名规范 的指导。
具体注意事项:
- 配合适当的
self约定,使用as_...()、to_...()或into_...()等前缀。另请参阅 Rust API 指南的这一章节 以及 Clippy lintwrong_self_convention。
生命周期命名
生命周期应使用描述性名称,类型生命周期尤其如此。
例外情况:
- 像
Cow这类极其通用的抽象中的类型生命周期。 - 能用匿名生命周期(
'_)的地方就用匿名生命周期。 - 单个字母的生命周期可以用在两种场景:表达方法输入与输出之间的关系,或者局部的高阶生命周期约束(
for<'a>)。这种局部生命周期最多允许两个,如果需要更多,强烈建议使用描述性名称。
泛型参数命名
泛型参数用短名称(单个或多个字符都可以),名称要与其代表的类型类别相关。单个字母的泛型没问题,但选的字母最好能暗示对象类型,理想情况下取自最重要的 trait bound。
当泛型处于约束较少的上下文中时,用 T 或 U 就可以;也就是说,这个 API 面向大多数类型,比如 Vec<T>。
扩展 trait 命名
给扩展 trait 命名时,加上 ~Ext 后缀(例如 ForeignTypeExt)。
初始化函数命名
给初始化函数命名时遵循以下准则:
-
构造函数:用
new(),有多个时用new_with_foo()。如果构造函数返回Result,则用try_new()。 -
值到值的转换:用
from_foo(),并配套实现关联的Fromtrait。关于什么操作可以视为值到值的转换,详见 这里。
避免缩写
不要使用项目外部的人不太可能看懂的缩写(尤其是首字母缩略词),也不要通过删除单词中间字母的方式来缩写。
另请参阅 Google C++ Style Guide。
例外情况:
- Wikipedia 上能查到的常见缩写。
- 不易让项目外的人感到困惑的缩写,例如
IpAddr。这一判断由你和你自己的代码审查者共同做出。总体上,仍应避免使用缩写。
何时以及如何编写文档
为公共 API 添加文档注释,可考虑使用 missing_doc lint 来辅助这一工作。
文档注释的最佳实践:
-
考虑包含示例:并非每个函数都需要示例,但应在某处提供足够的功能示例,以便读者了解 crate 的使用方法。
-
始终为那些可能因输入格式错误而触发 panic 的函数记录 panic 情况。
-
明确记录 unsafe 函数和 trait 的不变量(invariants)。
-
使用大写开头和标点符号。
-
不要解释编程语言的基础知识。例如,不要这样做:
struct MockFileSystem { ... } /// A mock implementation of the FileSystem trait, intended to be used in unit tests. impl FileSystem for MockFileSystem
例外情况:
-
注释应包含代码本身未说明的内容。如果没有洞察性的内容可说,最好省略注释,而不是以平淡的方式重复函数名。例如,不要这样做(在这种情况下可以
allow该 lint):/// Removes an element. pub fn remove_element() -> Element {} -
通常可以省略单个枚举变体的文档,尤其是当名称本身已足够清晰时。
文档注释的格式规范
编写文档注释时请遵循以下指南:
- 使用
///注释来描述紧随其后的项目,如函数、struct、enum、trait 和类型别名。 - 使用
//!注释来描述模块或库本身。这些注释应放在文件顶部。 - 遵循官方 Rust 风格指南中关于文档注释的规则。
- 使用 Markdown 语法。
- 对于非文档注释(例如实现说明、对用户意义不大的 TODO、被注释掉的源码等),请继续使用普通注释语法(
//)。 - 推荐用直接的方式编写文档,使用
///和//!注释,而非通过宏生成文档。这样做能让读者在查看或修改源码时直接阅读文档内容。
将文档注释(/// 和 //!)与普通注释(//)混合使用不仅被允许,甚至被鼓励。如果某项内容需要公开文档说明,而另一项内容仅作为实现备注,不妨两者并用。例如:
/// Finds the first `FooItem` with the given `name`, or `None` if not present.
// TODO: crbug.com/12345 - `name` should be &str, not String.
pub fn get_named(items: &[FooItem], name: String) -> Option<&FooItem> {...}
设计依据
许多(尽管并非所有)语言对文档注释和实现注释采用不同的约定(例如添加额外的 * 字符)。Rust 和 Python 的特点在于,它们不仅在注释约定上有所区别,在语法层面也截然不同。这为 Rust 生态带来了切实的好处:
- 工具链可以消费文档注释,包括
rustdoc等文档生成器、IDE 功能以及 Kythe。 - 文档注释拥有标准的结构和格式规则(Markdown),使其在上述场景中支持富文本。
- 文档注释语法中的错误(例如将其应用于表达式而非可文档化的项)会由 Lint 检查捕获,从而尽早发现文档错误。如果没有 Lint 报错,则保证文档注释对文档工具可见,消除了文档过程中的不稳定性和不可预测性。
- 文档注释是 AST 的一部分,因此可以被宏生产和消费,包括
macro_rules!宏和过程宏。
其他 Rust 特性
不安全代码
除非无法用安全代码实现相同功能,否则不要编写不安全代码。
如果必须编写不安全代码:
- 将 unsafe 代码封装在安全抽象中,并尽可能与业务逻辑隔离。理想情况下,unsafe 代码应放在一个独立的 crate 里,除了标准库外尽量少依赖其他东西。
- 添加以
SAFETY:开头的安全性注释,说明代码为什么是正确的。 - 为 unsafe 代码提供技术上的理由。视具体场景,可以是针对某个 unsafe 块的理由,也可以是覆盖整个文件或构建目标的更宽泛的理由。这个理由应回答以下问题:
- 为什么这段代码不能用等效的安全写法实现?
- 如果原因是性能,有没有 benchmark 数据?
不使用不稳定特性
不要使用 unstable 特性。
例外情况:
- Android 嵌入式开发可能需要用到某些 unstable 特性。启用它们需要经过审核(以便寻找替代方案),但凡是正确构建产物所必需的特性,通常都会被批准。
- Chrome Style 的仲裁者可以为整个代码库统一批准一小批特性。通常只会批准那些有明确稳定化路径的特性。
- Fuchsia 相关指引见这里。
Getter 和 setter
Getter 和 setter 的编写与命名应遵循以下规范:
foo():按值返回T的 getter。foo_mut():返回&mut T的 getter。take_foo():先"清空"值(置为None或其他默认状态)再返回旧值的 getter。set_foo():接收一个按值传递的T的 setter。with_foo()/with_mut_foo():通过闭包进行操作的访问器(详见下文),调用方式形如object.with_foo(|foo| frob(foo))。replace_foo():返回旧值的 setter。
示例
impl Stuff {
fn foo(&self) -> &Foo { ... }
fn foo_mut(&mut self) -> &mut Foo { ... }
/// 将 "baz" 属性设为 `None`,并返回旧值。
fn take_baz(&mut self) -> Option<Baz> { ... }
fn set_foo(&mut self, foo: Foo) { ... }
/// 以 "bar" 属性的借用调用 `f`。
/// 返回 `f` 的返回值。
fn with_bar<R>(&self, f: impl FnOnce(&Bar) -> R) -> R { ... }
/// 以 "bar" 属性的可变借用调用 `f`。
/// 返回 `f` 的返回值。
fn with_mut_bar<R>(&self, f: impl FnOnce(&mut i32) -> R) -> R { ... }
/// 将 "foo" 属性设为 `foo`,并返回旧值。
fn replace_foo(&mut self, foo: Foo) -> Foo { ... }
}
关于接受闭包的访问器
接受闭包的访问器(.with_foo())通常的调用形式为
object.with_foo(|foo| do_something_with(foo))。在以下场景中它们是不错的选择:
-
当属性被包含在内部可变性包装器中(例如
Mutex或RefCell)时。这些机制需要将属性的访问限制在特定作用域内,而闭包提供了这一作用域。这通常优于直接返回实现作用域的 RAII 对象 (例如MutexGuard<T>),因为后者会泄漏实现细节。 -
当在属性更改后需要执行后续工作或验证,且无法使用
set_foo()访问器时(例如,因为属性的类型克隆成本过高或根本无法克隆)。
with_foo() 访问器通常允许闭包返回一个值,并通过 with_foo() 将其转发出去。
如果需要提供两个接受闭包的访问器,一个用于只读访问,另一个用于可变访问,通常命名为 with_foo() 和
with_mut_foo()。否则,with_foo() 也常用于可变访问器。
成组实现预期的 API
如果实现了 len(),请同时实现 is_empty()。作为背景,请参阅 Clippy
lint
len_without_is_empty。
不要访问非你所有的 #[doc(hidden)] 标记项
将标记为 #[doc(hidden)] 的项视为私有。除非你拥有该代码,否则请勿访问这些项。
负责任地使用 const 函数
只有当你预期该公共函数在未来仍会保持 const 状态(或承诺在变更时协助客户端进行迁移)时,才将其标记为 const。
理由
将 const 函数改为普通函数属于破坏性变更。
避免出于非数学目的使用运算符重载
使用运算符重载应遵循其原始的数学/逻辑用途,而不仅仅是为了让代码更简洁(即作为“语法糖”)。
为公开暴露的枚举应用 #[non_exhaustive]
如果某个枚举是公共 API 的一部分,且被其他团队使用,请将其标记为 #[non_exhaustive]。
例外情况:
- 该枚举永不变更。例如:
- 描述现有本体结构的枚举(例如
enum Color { Red, Green, Blue })。 - 仅有两种状态、可以用布尔值替代的枚举(例如
enum Visibility { Visible, Hidden })
- 描述现有本体结构的枚举(例如
- 该枚举未来可能会变更,但你承诺通过 LSC 修复由此引发的兼容性问题。
背景信息:请参阅 Clippy lint exhaustive_enums。
理由
将枚举标记为 #[non_exhaustive] 会强制用户在 match 语句中包含通配符分支(_ => ...)。这确保了将来向枚举添加新变体时,代码仍能正常编译。
这条规则主要适用于跨团队使用的枚举,因为破坏性变更的影响范围可能很大。仅在少数地方使用的枚举不会造成大范围破坏,因此可以忽略此规则。
为包含公开字段的公共结构体应用 #[non_exhaustive]
包含公开字段且作为公共 API 一部分、供其他团队使用的结构体,应标记为 #[non_exhaustive]。
例外情况:
- 结构体字段不太可能变更,例如因为它们描述了现有本体结构(例如 Rectangle 类型),或者审查者可以确信它们不会变更。
- 该 struct 的字段将来可能会变动,但你承诺会通过 LSC 修复由此造成的破坏。
- 你希望用户能够使用函数式记录更新(FRU)的 struct 初始化语法(
Person { name: "foo", ..Default::default() })。
理由
给一个字段全为公开的 struct 新增字段(即使是私有字段)属于破坏性变更,因为调用方将无法在 struct 字面量中列出所有字段。
#[non_exhaustive] 的 struct 无法用 struct 字面量语法构造,除非代码在同一个 crate 内。这样就可以在不破坏用户的前提下新增私有字段。
这条规则主要对跨团队使用的 struct 重要,因为破坏的影响范围可能很大。只被少量使用的 struct 不会造成大的破坏,因此可以忽略这条规则。
函数上的 #[must_use]
在以下情况下给函数加 #[must_use]:
-
调用方如果忽略返回值就无法正确使用该函数。这包括纯函数(无副作用的函数),例如
HashMap::get()。 -
返回值代表错误或关于函数行为的关键信息的任何函数。如果返回类型本身已经标注了
#[must_use](例如Result就是如此),则函数无需再标注#[must_use]。
类型上的 #[must_use]
对于本应按照上述规则给函数标注 #[must_use] 的情况,可以改为在其返回类型上加 #[must_use]。
例如:
-
该类型是错误类型(类似于
Result或StatusOr)。 -
该类型表示惰性求值的计算。也就是说,函数调用本身不做任何事情,必须访问返回值才会触发预期的副作用。
不要在 main() 之前运行代码
不要让代码在 main() 之前运行,例如通过 ctor crate 这类手段。
实现层面的考量
不要过度依赖类型推断
加上足够的显式类型标注,让熟悉该代码库的人能推断出省略部分的类型。
优先在变量声明处添加类型,而非使用 turbofish 语法。如果编译器强制要求使用 turbofish,通常添加一个 _ 作为类型推断标记即可。
以下情况建议显式添加类型:
- 调用具有泛型返回值的函数,例如
.into()或.parse()。 - 处理复杂迭代器链的返回结果。
优先使用模式匹配而非先检查后 unwrap
当输入数据已保证不会触发 panic 时,避免使用可能触发 panic 的操作。例如,对于已知有效的值,不要用 Option::unwrap,而用模式匹配向编译器证明逻辑正确。
// 推荐:match 分支向编译器证明 `x` 是 `Some`。
// 显然不会发生 panic。
if let Some(value) = option {
use_value(value);
}
// 不推荐:`unwrap` 的正确性依赖运行时检查 `option` 是否为 `Some`。
if option.is_some() {
use_value(option.unwrap());
}
优先使用 expect 而非 unwrap
如果因无法在类型系统中表达不变量而必须使用 panic,请优先使用 expect 代替 unwrap,以便记录原因。
对 non_exhaustive 枚举进行模式匹配时,不要省略匹配分支
在 non_exhaustive 枚举的 match 语句中,建议列出所有枚举变体。
如果不关心具体变体,将其归入通配符分支。如果只关心部分变体,使用 if let 或 let … else {}。
示例:
#[non_exhaustive]
pub enum Shape {
Circle,
Square,
Triangle,
}
fn process_shape(shape: Shape) {
match shape {
Shape::Circle => println!("It's a circle"),
Shape::Square => println!("It's a square"),
// Triangle 及未来新增的变体无需处理。
Shape::Triangle | _ => {}
}
}
fn process_shape(shape: Shape) {
if let Shape::Circle = shape {
println!("It's a circle"),
}
}
fn process_shape(shape: Shape) {
match shape {
Shape::Circle => println!("It's a circle"),
_ => {}
}
}
例外情况:
- 你只关心特定的变体,且 使用
match比if let更清晰。
内置 Lint 规则 non_exhaustive_omitted_patterns 覆盖了此情形,你可以在代码中启用该规则。
使用上下文字符串来阐明断言
虽然有些断言不言自明,但许多断言通过补充上下文会更清晰,这有助于说明为什么断言预期成立,或是什么导致了断言失败。使用 assert! 的可选格式化字符串参数来传达这些上下文。
你应当始终考虑添加上下文,尤其是在以下情况下:
- 如果你打算为断言添加注释。请改用格式化字符串:这样做的好处是它会被记录在日志中。
- 如果你预期断言失败时会被用户看到。在这种情况下,人类可读的解释比 Rust 表达式更有帮助。
- 如果记录某个值有助于理解断言为何失败。
- 为了澄清断言失败意味着:
- 客户端误用了 API(即,他们应改变使用方式),或
- 实现中包含 Bug(即,客户端应提交 Bug 报告)。
示例
解释为什么断言应该成立
assert!(
values.is_sorted(),
"`values` is populated from a `PriorityQueue`, so we expect it to be sorted"
);
记录值以阐明断言失败的原因
assert!(refund > 0, "Refund must be positive, got {refund:?});
标记 API 的误用
impl Database {
...
fn execute_query(&self, query: &str) {
assert!(self.stream.is_some(), "Call connect() before executing queries");
}
...
}
不要仅为了重复条件而使用上下文字符串
assert(!values.is_sorted(), "values should always be sorted");
当直接迭代更清晰时,不要使用迭代器组合器链
避免以损害可读性的方式使用组合器链。具体而言:
- 避免冗长复杂的组合器链。
- 不要在
for循环的头部构建组合器链,而是先把组合器链赋值给一个变量,再在for循环中使用这个变量。 - 避免使用
Iterator::for_each,除非你有充分的理由。for循环通常更易读。
对于较短的链式调用,或者组合器本身就封装了大量逻辑、用 for 循环反而要写更多代码的场景,优先选择组合器。
示例
复杂的组合器链
下面的组合器链因为包含条件判断和修改外部状态,可读性很差:
let mut error_count = 0;
let _processed_items: Vec<_> = items
.into_iter()
.map(transformation_that_may_fail)
.map(|result| {
if result.is_err() {
error_count += 1;
}
result
})
.filter_map(Result::ok)
.collect();
等价的 for 循环更易读:
let mut error_count = 0;
let mut processed_items = Vec::with_capacity(items.len());
for item in items {
match transformation_that_may_fail(item) {
Ok(val) => processed_items.push(val),
Err(_) => error_count += 1,
}
}
for 循环中的组合器链
不要在 for 循环的头部构建组合器链:
for bug in bug_descriptions
.iter()
.filter_map(|description| parse_bug_description(description).ok())
.filter(|bug| bug.priority <= Priority::P1)
{
assign_bug(bug);
}
应改为先把组合器链赋值给变量,这样代码更清爽,变量名也能说明这条链的用途:
let urgent_bugs = bug_descriptions
.iter()
.filter_map(|description| parse_bug_description(description).ok())
.filter(|bug| bug.priority <= Priority::P1);
for bug in urgent_bugs {
assign_bug(bug);
}
何时优先使用组合器链
下面是一个更适合用组合器链的例子:
let threshold_exceeded = values.iter().any(|&v| v > threshold);
对应的 for 循环可读性较差,且重复实现了 any() 中已有的逻辑:
let mut threshold_exceeded = false;
for v in values {
if v > threshold {
threshold_exceeded = true;
break;
}
}
不要调用 panic::catch_unwind
禁止在 Rust 第一方代码中使用 panic::catch_unwind。
例外情况:
- 可以作为纵深防御机制使用,但绝不能 依赖 它来保证任何属性。如果代码库已经在努力避免 panic,可以选择在关键入口点包裹
catch_unwind恢复机制,以防某个 panic 意外穿透。代码作者必须让审查者确信,代码库已经尽力避免 panic。此例外仅适用于可能以panic=unwind模式运行的代码(因此不适用于 Chrome、Android 和 Fuchsia)。
理由
Rust 代码可能运行在许多环境中,而 panic::catch_unwind 仅在支持 panic=unwind 的环境中才能正常工作。虽然生产二进制的最终 panic 处理策略尚未确定,但 Chrome、Android 和 Fuchsia 都要求使用 panic=abort。
字符串拼接和替换优先使用 format! / write!
在以下场景中,优先使用 format!() 和 write!() 而非其他替代方案:
- 拼接两个以上的字符串。例如,使用
format!("{a}{b}{c}")代替a + b + c。 - 对字面量字符串进行替换(而非使用
str::replace)。
理由
- 使用
+拼接字符串时,format!/write!所需的内存分配更少。 - 优先使用标准格式字符串,不要自创模板语法。