Rust 命名规范

命名规范

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

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

条目	惯例
包 Crates	unclear
模块 Modules	snake_case
类型 Types	UpperCamelCase
特征 Traits	UpperCamelCase
枚举 Enumerations	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。

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

推荐几款学习编程的免费平台

免费在线开发平台（https://docs.ltpp.vip/LTPP/）

       探索编程世界的新天地，为学生和开发者精心打造的编程平台，现已盛大开启！这个平台汇集了近4000道精心设计的编程题目，覆盖了C、C++、JavaScript、TypeScript、Go、Rust、PHP、Java、Ruby、Python3以及C#等众多编程语言，为您的编程学习之旅提供了一个全面而丰富的实践环境。       
      在这里，您不仅可以查看自己的代码记录，还能轻松地在云端保存和运行代码，让编程变得更加便捷。平台还提供了私聊和群聊功能，让您可以与同行们无障碍交流，分享文件，共同进步。不仅如此，您还可以通过阅读文章、参与问答板块和在线商店，进一步拓展您的知识边界。
       为了提升您的编程技能，平台还设有每日一题、精选题单以及激动人心的编程竞赛，这些都是备考编程考试的绝佳资源。更令人兴奋的是，您还可以自定义系统UI，选择视频或图片作为背景，打造一个完全个性化的编码环境，让您的编程之旅既有趣又充满挑战。

免费公益服务器（https://docs.ltpp.vip/LTPP-SHARE/linux.html）

       作为开发者或学生，您是否经常因为搭建和维护编程环境而感到头疼？现在，您不必再为此烦恼，因为一款全新的免费公共服务器已经为您解决了所有问题。这款服务器内置了多种编程语言的编程环境，并且配备了功能强大的在线版VS Code，让您可以随时随地在线编写代码，无需进行任何复杂的配置。
随时随地，云端编码
       无论您身在何处，只要有网络连接，就可以通过浏览器访问这款公共服务器，开始您的编程之旅。这种云端编码的便利性，让您的学习或开发工作不再受限于特定的设备或环境。
丰富的编程语言支持
       服务器支持包括C、C++、JavaScript、TypeScript、Go、Rust、PHP、Java、Ruby、Python3以及C#等在内的多种主流编程语言，满足不同开发者和学生的需求。无论您是初学者还是资深开发者，都能找到适合自己的编程环境。
在线版VS Code，高效开发
       内置的在线版VS Code提供了与本地VS Code相似的编辑体验，包括代码高亮、智能提示、代码调试等功能，让您即使在云端也能享受到高效的开发体验。
数据隐私和安全提醒
       虽然服务器是免费的，但为了保护您的数据隐私和安全，我们建议您不要上传任何敏感或重要的数据。这款服务器更适合用于学习和实验，而非存储重要信息。

免费公益MYSQL（https://docs.ltpp.vip/LTPP-SHARE/mysql.html）

       作为一名开发者或学生，数据库环境的搭建和维护往往是一个复杂且耗时的过程。但不用担心，现在有一款免费的MySQL服务器，专为解决您的烦恼而设计，让数据库的使用变得简单而高效。
性能卓越，满足需求
       虽然它是免费的，但性能绝不打折。服务器提供了稳定且高效的数据库服务，能够满足大多数开发和学习场景的需求。
在线phpMyAdmin，管理更便捷
       内置的在线phpMyAdmin管理面板，提供了一个直观且功能强大的用户界面，让您可以轻松地查看、编辑和管理数据库。
数据隐私提醒，安全第一
       正如您所知，这是一项公共资源，因此我们强烈建议不要上传任何敏感或重要的数据。请将此服务器仅用于学习和实验目的，以确保您的数据安全。

免费在线WEB代码编辑器（https://docs.ltpp.vip/LTPP-WEB-IDE/）

       无论你是开发者还是学生，编程环境的搭建和管理可能会占用你宝贵的时间和精力。现在，有一款强大的免费在线代码编辑器，支持多种编程语言，让您可以随时随地编写和运行代码，提升编程效率，专注于创意和开发。
多语言支持，无缝切换
       这款在线代码编辑器支持包括C、C++、JavaScript、TypeScript、Go、Rust、PHP、Java、Ruby、Python3以及C#在内的多种编程语言，无论您的项目需要哪种语言，都能在这里找到支持。
在线运行，快速定位问题
       您可以在编写代码的同时，即时运行并查看结果，快速定位并解决问题，提高开发效率。
代码高亮与智能提示
       编辑器提供代码高亮和智能提示功能，帮助您更快地编写代码，减少错误，提升编码质量。

免费二维码生成器（https://docs.ltpp.vip/LTPP-QRCODE/）

       二维码（QR Code）是一种二维条码，能够存储更多信息，并且可以通过智能手机等设备快速扫描识别。它广泛应用于各种场景，如：
企业宣传
       企业可以通过二维码分享公司网站、产品信息、服务介绍等。
活动推广
       活动组织者可以创建二维码，参与者扫描后可以直接访问活动详情、报名链接或获取电子门票。
个人信息分享
       个人可以生成包含联系方式、社交媒体链接、个人简历等信息的二维码。
电子商务
       商家使用二维码进行商品追踪、促销活动、在线支付等。
教育
       教师可以创建二维码，学生扫描后可以直接访问学习资料或在线课程。
交通出行
       二维码用于公共交通的票务系统，乘客扫描二维码即可进出站或支付车费。        功能强大的二维码生成器通常具备用户界面友好，操作简单，即使是初学者也能快速上手和生成的二维码可以在各种设备和操作系统上扫描识别的特点。