← 文章 / 编程开发
Hacker News 2026/10/22 · 2026-10-22 11:53:12 · 25 阅读

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]

在 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 选项:

  • 宏匹配器的格式化: 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 类型:尽量实现 Copy trait。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)。

    重要的 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 课程中关于 命名规范 的指导。

    具体注意事项:

    生命周期命名

    生命周期应使用描述性名称,类型生命周期尤其如此。

    例外情况:

    • 像 Cow 这类极其通用的抽象中的类型生命周期。
    • 能用匿名生命周期('_)的地方就用匿名生命周期。
    • 单个字母的生命周期可以用在两种场景:表达方法输入与输出之间的关系,或者局部的高阶生命周期约束(for<'a>)。这种局部生命周期最多允许两个,如果需要更多,强烈建议使用描述性名称。

    泛型参数命名

    泛型参数用短名称(单个或多个字符都可以),名称要与其代表的类型类别相关。单个字母的泛型没问题,但选的字母最好能暗示对象类型,理想情况下取自最重要的 trait bound。

    当泛型处于约束较少的上下文中时,用 T 或 U 就可以;也就是说,这个 API 面向大多数类型,比如 Vec<T>。

    扩展 trait 命名

    给扩展 trait 命名时,加上 ~Ext 后缀(例如 ForeignTypeExt)。

    初始化函数命名

    给初始化函数命名时遵循以下准则:

    • 构造函数:用 new(),有多个时用 new_with_foo()。如果构造函数返回 Result,则用 try_new()。

    • 值到值的转换:用 from_foo(),并配套实现关联的 From trait。关于什么操作可以视为值到值的转换,详见 这里。

    避免缩写

    不要使用项目外部的人不太可能看懂的缩写(尤其是首字母缩略词),也不要通过删除单词中间字母的方式来缩写。

    另请参阅 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! 所需的内存分配更少。
    • 优先使用标准格式字符串,不要自创模板语法。

    使用适合各代码库的测试框架

    原始来源: Hacker News

    评论 (0)