《深入Rust系统编程》B: Rust代码风格指南

January 18, 2025

附录 B: Rust 代码风格指南

Rust 是一种注重安全性和性能的系统编程语言，其设计哲学强调代码的可读性、一致性和可维护性。为了帮助开发者编写高质量的 Rust 代码，Rust 社区制定了一套代码风格指南。本文将深入探讨 Rust 的代码风格指南，涵盖命名规范、代码格式化、注释规范、模块组织等内容，并结合实际示例进行说明。

1. 命名规范

1.1 通用命名规则

Rust 的命名规范遵循以下原则：

清晰性：名称应清晰表达其含义。
一致性：相同类型的名称应遵循相同的风格。
简洁性：名称应尽量简洁，但不应牺牲清晰性。

1.2 变量和函数命名

变量名：使用 snake_case，即小写字母和下划线组合。例如：
1 2

let user_name = "Alice"; let max_count = 100;

函数名：使用 snake_case。例如：

1
2
3


fn calculate_area(width: u32, height: u32) -> u32 {
    width * height
}

1.3 类型命名

结构体、枚举和特质：使用 PascalCase，即首字母大写的驼峰命名法。例如：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13


struct UserProfile {
    name: String,
    age: u32,
}

enum HttpStatus {
    Ok,
    NotFound,
}

trait Drawable {
    fn draw(&self);
}

1.4 常量和静态变量

常量：使用 SCREAMING_SNAKE_CASE，即全大写字母和下划线组合。例如：
1

const MAX_USERS: u32 = 100;
静态变量：使用 SNAKE_CASE。例如：
1

static mut COUNTER: u32 = 0;

1.5 模块和文件命名

模块名：使用 snake_case。例如：
1

mod network_utils;
文件名：与模块名一致，使用 snake_case。例如：
1

network_utils.rs

2. 代码格式化

2.1 缩进与空格

缩进：使用 4 个空格，而不是制表符。
空格：
- 在二元运算符两侧添加空格。例如：
  1
  
  let sum = a + b;
- 在逗号后添加空格。例如：
  1
  
  let list = vec![1, 2, 3];
- 在冒号后添加空格。例如：
  1
  
  let name: String = "Alice".to_string();

2.2 换行与空行

换行：

每行代码不应超过 100 个字符。

如果函数参数过多，可以将参数分行书写。例如：

1
2
3
4
5
6
7


fn process_data(
    data: Vec<u32>,
    threshold: u32,
    options: Option<ProcessingOptions>,
) -> Result<(), Error> {
    // 函数体
}

空行：
- 在函数、结构体、枚举等定义之间添加空行。
- 在逻辑相关的代码块之间添加空行，以提高可读性。

2.3 大括号与代码块

大括号：
- 左大括号 { 应与关键字（如 fn、if）在同一行。
- 右大括号 } 应独占一行。例如：
  1 2 3
  
  fn main() { println!("Hello, world!"); }
代码块：
- 如果代码块只有一行，可以省略大括号。例如：
  1 2 3
  
  if condition { do_something(); }

3. 注释规范

3.1 单行注释

使用 // 进行单行注释。例如：

1
2


// 计算两个数的和
let sum = a + b;

3.2 多行注释

使用 /* ... */ 进行多行注释。例如：

1
2
3
4


/*
这是一个多行注释，
用于解释复杂的逻辑。
*/

3.3 文档注释

使用 /// 为函数、结构体、枚举等添加文档注释。例如：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


/// 计算矩形的面积。
///
/// # 参数
/// - `width`: 矩形的宽度。
/// - `height`: 矩形的高度。
///
/// # 返回值
/// 返回矩形的面积。
fn calculate_area(width: u32, height: u32) -> u32 {
    width * height
}

3.4 模块注释

使用 //! 为模块添加注释。例如：

1
2
3


//! 网络工具模块。
//!
//! 该模块提供了与网络相关的实用函数。

4. 模块与文件组织

4.1 模块划分

将功能相关的代码组织到同一个模块中。
避免创建过大的模块，尽量将模块拆分为多个子模块。

4.2 文件结构

每个模块对应一个文件。

如果模块包含子模块，可以将其放在一个目录中。例如：

1
2
3
4
5
6


src/
├── main.rs
├── network/
│   ├── mod.rs
│   ├── tcp.rs
│   └── udp.rs

4.3 可见性

使用 pub 关键字控制模块、函数、结构体等的可见性。
尽量限制可见性，避免暴露不必要的接口。

5. 错误处理

5.1 使用 `Result` 和 `Option`

使用 Result 处理可能失败的操作。例如：

1
2
3
4
5
6
7


fn divide(a: f64, b: f64) -> Result<f64, String> {
    if b == 0.0 {
        Err("Division by zero".to_string())
    } else {
        Ok(a / b)
    }
}

使用 Option 处理可能为空的值。例如：

1
2
3


fn find_user(id: u32) -> Option<User> {
    // 查找用户
}

5.2 错误传播

使用 ? 运算符简化错误传播。例如：

1
2
3
4
5
6


fn read_file(path: &str) -> Result<String, io::Error> {
    let mut file = File::open(path)?;
    let mut contents = String::new();
    file.read_to_string(&mut contents)?;
    Ok(contents)
}

6. 测试与文档

6.1 单元测试

将单元测试放在 #[cfg(test)] 模块中。例如：

1
2
3
4
5
6
7
8
9


#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn test_add() {
        assert_eq!(add(2, 3), 5);
    }
}

6.2 文档测试

在文档注释中添加示例代码，并使用 cargo test 运行文档测试。例如：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


/// 计算两个数的和。
///
/// # 示例
/// ```
/// let result = add(2, 3);
/// assert_eq!(result, 5);
/// ```
fn add(a: i32, b: i32) -> i32 {
    a + b
}

7. 工具支持

7.1 Rustfmt

Rustfmt 是 Rust 的官方代码格式化工具，用于自动格式化代码。可以通过以下命令安装和使用：

1
2


rustup component add rustfmt
cargo fmt

7.2 Clippy

Clippy 是 Rust 的代码检查工具，用于发现潜在的问题和改进代码质量。可以通过以下命令安装和使用：

1
2


rustup component add clippy
cargo clippy

8. 总结

Rust 的代码风格指南旨在帮助开发者编写高质量、可维护的代码。通过遵循命名规范、代码格式化规则、注释规范和模块组织原则，开发者可以提高代码的可读性和一致性。同时，利用 Rust 的工具链（如 Rustfmt 和 Clippy）可以进一步优化代码质量。