rust-course/contents/practice/naming.md

命名规范

基本的 Rust 命名规范在 RFC 430 中有描述。

通常，对于 type-level 的构造 Rust 倾向于使用驼峰命名法，而对于 value-level 的构造使用蛇形命名法。详情如下：

条目	惯例
包 Crates	unclear
模块 Modules	snake_case
类型 Types	UpperCamelCase
特征 Traits	UpperCamelCase
枚举 Emumerations	UpperCamelCase
结构体 Structs	UpperCamelCase
函数 Functions	snake_case
方法 Methods	snake_case
通用构造器 General constructors	new or with_more_details
转换构造器 Conversion constructors	from_some_other_type
宏 Macros	snake_case!
局部变量 Local variables	snake_case
静态类型 Statics	SCREAMING_SNAKE_CASE
常量 Constants	SCREAMING_SNAKE_CASE
类型参数 Type parameters	UpperCamelCase，通常使用一个大写字母: T
生命周期 Lifetimes	通常使用小写字母: 'a，'de，'src
Features	unclear but see C-FEATURE

对于驼峰命名法，复合词的缩略形式我们认为是一个单独的词语，所以只对首字母进行大写：使用 Uuid 而不是 UUID，Usize 而不是 USize，Stdin 而不是 StdIn。

对于蛇形命名法，缩略词用全小写：is_xid_start。

对于蛇形命名法（包括全大写的 SCREAMING_SNAKE_CASE），除了最后一部分，其它部分的词语都不能由单个字母组成： btree_map 而不是 b_tree_map，PI_2 而不是 PI2.

包名不应该使用 -rs 或者 -rust 作为后缀，因为每一个包都是 Rust 写的，因此这种多余的注释其实没有任何意义。

特征命名

特征的名称应该使用动词，而不是形容词或者名词，例如 Print 和 Draw 明显好于 Printable 和 Drawable。

类型转换要遵守 as_，to_，into_ 命名惯例(C-CONV)

类型转换应该通过方法调用的方式实现，其中的前缀规则如下：

方法前缀	性能开销	所有权改变
as_	Free	borrowed -> borrowed
to_	Expensive	borrowed -> borrowed borrowed -> owned (non-Copy types) owned -> owned (Copy types)
into_	Variable	owned -> owned (non-Copy types)

例如：

• str::as_bytes() 把 str 变成 UTF-8 字节数组，性能开销是 0。输入是一个借用的 &str，输出也是一个借用的 &str
• Path::to_str 会执行一次昂贵的 UTF-8 字节数组检查，输入和输出都是借用的。对于这种情况，如果把方法命名为 as_str 是不正确的，因为这个方法的开销还挺大
• str::to_lowercase() 在调用过程中会遍历字符串的字符，且可能会分配新的内存对象。输入是一个借用的 str，输出是一个有独立所有权的 String
• String::into_bytes() 返回 String 底层的 Vec<u8> 数组，转换本身是零消耗的。该方法获取 String 的所有权，然后返回一个新的有独立所有权的 Vec<u8>

当一个单独的值被某个类型所包装时，访问该类型的内部值应通过 into_inner() 方法来访问。例如将一个缓冲区值包装为 BufReader 类型，还有 GzDecoder、AtomicBool 等，都是这种类型。

如果 mut 限定符在返回类型中出现，那么在命名上也应该体现出来。例如，Vec::as_mut_slice 就说明它返回了一个 mut 切片，在这种情况下 as_mut_slice 比 as_slice_mut 更适合。

// 返回类型是一个 `mut` 切片
fn as_mut_slice(&mut self) -> &mut [T];

标准库中的一些例子

• Result::as_ref
• RefCell::as_ptr
• slice::to_vec
• Option::into_iter

读访问器(Getter)的名称遵循 Rust 的命名规范(C-GETTER)

除了少数例外，在 Rust代码中 get 前缀不用于 Getter。

pub struct S {
    first: First,
    second: Second,
}

impl S {
    // 而不是 get_first
    pub fn first(&self) -> &First {
        &self.first
    }

    // 而不是 get_first_mut，get_mut_first，or mut_first
    pub fn first_mut(&mut self) -> &mut First {
        &mut self.first
    }
}

至于上文提到的少数例外，如下：当有且仅有一个值能被 Getter 所获取时，才使用 get 前缀。例如，Cell::get 能直接访问到 Cell 中的内容。

有些 Getter 会在过程中执行运行时检查，那么我们就可以考虑添加 _unchecked Getter 函数，这个函数虽然不安全，但是往往具有更高的性能。 典型的例子如下：

fn get(&self, index: K) -> Option<&V>;
fn get_mut(&mut self, index: K) -> Option<&mut V>;
unsafe fn get_unchecked(&self, index: K) -> &V;
unsafe fn get_unchecked_mut(&mut self, index: K) -> &mut V;

标准库示例

• std::io::Cursor::get_mut
• std::ptr::Unique::get_mut
• std::sync::PoisonError::get_mut
• std::sync::atomic::AtomicBool::get_mut
• std::collections::hash_map::OccupiedEntry::get_mut
• <[T]>::get_unchecked

一个集合上的方法，如果返回迭代器，需遵循命名规则：iter，iter_mut，into_iter (C-ITER)

fn iter(&self) -> Iter             // Iter implements Iterator<Item = &U>
fn iter_mut(&mut self) -> IterMut  // IterMut implements Iterator<Item = &mut U>
fn into_iter(self) -> IntoIter     // IntoIter implements Iterator<Item = U>

上面的规则适用于同构性的数据集合。与之相反，str 类型是一个 UTF-8 字节数组切片，与同构性集合有一点微妙的差别，它可以认为是字节集合，也可以认为是字符集合，因此它提供了 str::bytes 去遍历字节，还有 str::chars 去遍历字符，而并没有直接定义 iter 等方法。

上述规则只适用于方法，并不适用于函数。例如 url 包的 percent_encode 函数返回一个迭代器用于遍历百分比编码（Percent encoding）的字符串片段. 在这种情况下，使用 iter/iter_mut/into_iter 诸如此类的函数命名无法表达任何具体的含义。

标准库示例

• Vec::iter
• Vec::iter_mut
• Vec::into_iter
• BTreeMap::iter
• BTreeMap::iter_mut

迭代器的类型应该与产生它的方法名相匹配(C-ITER-TY)

例如形如 into_iter() 的方法应该返回一个 IntoIter 类型，与之相似，其它任何返回迭代器的方法也应该遵循这种命名惯例。

上述规则主要应用于方法，但是经常对于函数也适用。例如上文提到的 url 包中的 percent_encode 函数，返回了一个 PercentEncode 类型。

特别是，当这些类型跟包名前缀一起使用时，将具备非常清晰的含义，例如 vec::IntoIter。

标准库示例

• Vec::iter returns Iter
• Vec::iter_mut returns IterMut
• Vec::into_iter returns IntoIter
• BTreeMap::keys returns Keys
• BTreeMap::values returns Values

Cargo Feature 的名称不应该包含占位词(C-FEATURE)

不要在 Cargo feature 中包含无法传达任何意义的词，例如 use-abc 或 with-abc，直接命名为 abc 即可。

一个典型的例子就是：一个包对标准库有可选性的依赖。标准的写法如下：

# 在 Cargo.toml 中

[features]
default = ["std"]
std = []

// 在我们自定义的 lib.rs 中

#![cfg_attr(not(feature = "std"), no_std)]

除了 std 之外，不要使用任何 ust-std 或者 with-std 等自以为很有创造性的名称。

命名要使用一致性的词序(C-WORD-ORDER)

这是一些标准库中的错误类型:

• JoinPathsError
• ParseBoolError
• ParseCharError
• ParseFloatError
• ParseIntError
• RecvTimeoutError
• StripPrefixError

它们都使用了 谓语-宾语-错误 的词序，如果我们想要表达一个网络地址无法分析的错误，由于词序一致性的原则，命名应该如下 ParseAddrError，而不是 AddrParseError。

词序和个人习惯有很大关系，想要注意的是，你可以选择合适的词序，但是要在包的范畴内保持一致性，就如标准库中的包一样。