附录 B: Rust 代码风格指南

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

1. 命名规范

1.1 通用命名规则

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

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

1.2 变量和函数命名

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

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

• 函数名：使用 snake_case。例如：

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

1.3 类型命名

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

  struct UserProfile {
      name: String,
      age: u32,
  }
  
  enum HttpStatus {
      Ok,
      NotFound,
  }
  
  trait Drawable {
      fn draw(&self);
  }
  

1.4 常量和静态变量

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

  const MAX_USERS: u32 = 100;
  

• 静态变量：使用 SNAKE_CASE。例如：

  static mut COUNTER: u32 = 0;
  

1.5 模块和文件命名

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

  mod network_utils;
  

• 文件名：与模块名一致，使用 snake_case。例如：

  network_utils.rs
  

2. 代码格式化

2.1 缩进与空格

• 缩进：使用 4 个空格，而不是制表符。
• 空格：
  • 在二元运算符两侧添加空格。例如：

    let sum = a + b;
    

  • 在逗号后添加空格。例如：

    let list = vec![1, 2, 3];
    

  • 在冒号后添加空格。例如：

    let name: String = "Alice".to_string();
    

2.2 换行与空行

• 换行：
  • 每行代码不应超过 100 个字符。
  • 如果函数参数过多，可以将参数分行书写。例如：

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

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

2.3 大括号与代码块

• 大括号：
  • 左大括号 { 应与关键字（如 fn、if）在同一行。
  • 右大括号 } 应独占一行。例如：

    fn main() {
        println!("Hello, world!");
    }
    

• 代码块：
  • 如果代码块只有一行，可以省略大括号。例如：

    if condition {
        do_something();
    }
    

3. 注释规范

3.1 单行注释

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

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

3.2 多行注释

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

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

3.3 文档注释

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

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

3.4 模块注释

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

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

4. 模块与文件组织

4.1 模块划分

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

4.2 文件结构

• 每个模块对应一个文件。
• 如果模块包含子模块，可以将其放在一个目录中。例如：

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

4.3 可见性

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

5. 错误处理

5.1 使用 Result 和 Option

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

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

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

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

5.2 错误传播

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

  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)] 模块中。例如：

  #[cfg(test)]
  mod tests {
      use super::*;
  
      #[test]
      fn test_add() {
          assert_eq!(add(2, 3), 5);
      }
  }
  

6.2 文档测试

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

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

7. 工具支持

7.1 Rustfmt

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

rustup component add rustfmt
cargo fmt

7.2 Clippy

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

rustup component add clippy
cargo clippy

8. 总结

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