谷歌风格指南 Rust 风格指南 背景 适用范围 风格指南的目标 遵循公共 Rust 风格规则 在上下文中应用 API 设计规则 代码组织 优先使用小的 crate [chrome] 对 rust_library 源代码使用平面文件布局 [chrome] 根据主要用户定义的项目命名源文件和叶模块 不要在非叶模块中实现 API 不要使用全局导入 一个 use 语句应从一个模块中导入项目 优先导入本地作用域的 trait 定义 使用模块名称限定对顶级函数的调用 类型名称应无限定地导入和使用 使用适当的导入机制 [chrome] 代码格式化和美观 使用适当的格式化工具 选择不使用自动格式化 拥有权和借用 避免使用 Rc 和 Arc 优先使用借用而非深拷贝 函数输入和输出 接受不可变数据的灵活引用 返回类型中的迭代器与拥有的集合 函数参数中的迭代器与切片 接受 Into 在 API 中优先使用枚举而非布尔值 报告错误 类型 新类型与类型别名 优先使用命名字段而非元组和非新类型元组结构 Trait 实现必要时添加 trait 实现已知标准库 trait 而非自定义方法 尽可能使用 #[derive()] 泛型与 dyn Trait 何时定义 trait 与固有实现 扩展 trait 重要 trait 的具体指导 将重要的 From impls 与显式构造方法配对 Options 结构应实现 Default 并发 处理毒性 不要通过 Rust 标准库启动新线程 [chrome] 使用 fuchsia_sync::Mutex [Fuchsia] 宏 命名 命名方法 命名生命周期 命名泛型参数 命名扩展 trait 命名初始化函数 避免缩写 何时以及如何编写文档 其他 Rust 特性 不安全代码 无不稳定特性 Getter 和 setter 更关于接受闭包的访问器 实现预期的 API 集 不要访问你不拥有的标记为 #[doc(hidden)] 的项目 负责任地使用 const 函数 避免为非数学目的重载 对公开的枚举应用 #[non_exhaustive] 对具有公共字段的公开结构应用 #[non_exhaustive] 对函数应用 #[must_use] 对类型应用 #[must_use] 不要在 main() 之前运行代码 实现注意事项 不要过度使用类型推断 优先使用模式匹配而非检查然后解包 优先使用 expect 而非 unwrap 在对非详尽枚举进行匹配时不要省略模式 使用上下文字符串澄清断言 当直接迭代更清晰时，不要使用迭代器组合调用链 不要调用 panic::catch_unwind 优先使用 format! / write! 进行拼接和替换 使用正确的每个代码库测试框架 本文档是谷歌使用 Rust 编程语言的风格指南。在这个上下文中，“风格”不仅仅指格式化；它还包括 API 和实现设计的指导。Rust 在许多地方使用，包括 google3、Android、ChromeOS、Fuchsia 和 Chrome，我们希望谷歌的 Rust 使用在各个代码库之间和内部保持一致。除了为我们的 Rust 代码带来一致性，风格指导也有助于建立质量标准。背景 适用范围 本指南中所述规则的当前授权范围：在 Android、Chromium 和其他代码库中：本风格指南是经过与其他代码库协商后开发的，并且他们打算开始应用它。这些代码库可能有其自己的规则，关于如何严格地期望应用这些规则。随着这些代码库采纳本指南，期待在这里有更多信息。风格指南的目标 总的来说，我们编写此文档的原因与我们的 C++ 风格指南是一样的。大部分风格规则来自以下列出的一个或多个目标。风格规则应优先考虑可读性和可维护性而非可写性 我们期望我们的代码能够持续存在较长时间，我们认为在代码编写过程中施加一点额外的努力是值得的，如果该风格规则提高了可读性。风格规则应更有利于更好的自动化 在谷歌，大规模变更（LSCs）很常见，一致性有助于使 LSC 更容易执行。风格规则应尽可能与更广泛的 Rust 生态系统保持一致 更广泛的 Rust 生态系统中，风格已经有一定程度的一致性，我们应该在可能的情况下依赖这一点，以减少惊讶并减轻学习谷歌 Rust 风格的工作。风格规则应有其价值 每个在谷歌的 Rust 开发者和审查者都必须牢记这些风格规则：因此，我们应当小心地包含那些有实质性好处的规则。风格规则可能有助于避免小的风格争议 有很多情况下，合理的人们可能会对一种风格有不同看法，我们期望这种争议在 CL 中经常出现。有一个风格规则有助于避免每次都重新讨论这个问题。