命名与文档

提炼自指南的 Naming 与 When and how to write documentation 章节。

命名

方法命名

遵循 Rust 标准库的方法命名风格。as_…() / to_…() / into_…() 等前缀要与相应的 self 参数约定匹配（借用 / 复制 / 消耗）。对应 clippy wrong_self_convention；另见 Comprehensive Rust 的命名约定。

生命周期命名

• 生命周期用描述性名称，类型生命周期尤其如此。
• 例外：极端泛型的抽象（如 Cow）；能用匿名生命周期 '_ 的地方就用；表达方法输入与输出关系、或局部 higher-ranked 约束（for<'a>）时可用单字符——此类最多两个，再多强烈建议改用描述性名称。

泛型参数命名

用与所代表事物相关的短名（单字符或多字符）。单字母可以，但字母应暗示类型，理想取自最重要的 trait bound。无约束场景用 T、U 即可（如 Vec<T>）。

扩展 trait 命名

以 Ext 结尾（原文记法 ~Ext 后缀），如 ForeignTypeExt。

初始化/构造函数命名

• 构造器：new()；多于一个时用 new_with_foo()；返回 Result 时用 try_new()。
• 值到值转换：from_foo()，并配对关联的 From 实现（何时应实现 From 见官方文档）。

避免缩写

不使用项目外的人不认识的缩写（尤其首字母缩写）；不用删字母式缩写。

例外：Wikipedia 上的常见缩写；项目外不会混淆的缩写（如 IpAddr）——由作者与 reviewer 判断，倾向仍然是不缩写。

文档注释

公开 API 必须有文档

可用 missing_docs lint 辅助。最佳实践：

• 覆盖示例：不必每个函数都有示例，但应在某处提供足够示例覆盖 crate 的主要功能，让人了解用法。
• 可能因畸形输入 panic 的函数，必须文档化 panic 条件。
• unsafe 函数与 trait：清晰文档化不变量（invariants）。
• 使用大写开头和标点。
• 不解释语言基础。反面示例：给 MockFileSystem 写 "A mock implementation of the FileSystem trait, intended to be used in unit tests."。
• 不简单复述：/// Removes an element. 配 remove_element() 不如不写（这种情况可 allow lint）。
• 枚举变体的文档可省略，名字自解释时尤其如此。

格式

• /// 文档化紧随其后的条目：函数、struct、enum、trait、类型别名。
• //! 文档化模块或库本身，放文件顶部。
• 遵循官方 Rust 风格指南对 doc comment 的要求；用 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> { … }