1# Rust语言代码风格 2 3  这篇文档将会介绍DragonOS中的Rust语言代码风格。随着开发的进行，这些风格可能会发生变化，但是我们会尽量保持风格的一致性。 4 5## 1. 命名 6 7  这部分基于Rust语言圣经中的[命名规范](https://course.rs/practice/naming.html)进行修改，本文未提及的部分，请参考Rust语言圣经中的[命名规范](https://course.rs/practice/naming.html)。 8 9## 2. 格式 10 11### 2.1 缩进 12 13  请在提交代码之前，使用`cargo fmt`命令对代码进行格式化。 14 15### 2.2 函数返回值 16 17  尽管Rust可以返回函数的最后一行的语句的值，但是，这种方式会使代码的可读性变差。因此，我们推荐您在函数的最后一行使用`return`语句，而不是直接返回值。 18 19```rust 20// 不推荐 21fn foo() -> i32 { 22 1 + 2 23} 24 25// 推荐 26fn foo() -> i32 { 27 return 1 + 2; 28} 29``` 30### 2.3 错误处理 31 32  DragonOS采用返回Posix错误码作为**模块间错误处理**的方式。为了确保在模块之间，错误处理代码的一致性，我们推荐在发生错误的时候，返回`Err(i32)`，并且posix错误码的值应当是负数。这样做的优点尤其体现在跨模块调用函数时，可以直接返回错误码，从而降低错误处理代码的耦合度。 33 34```rust 35// 函数跨越模块边界时（由其他模块调用当前函数），不推荐 36fn foo() -> Result<(), CustomErr> { 37 if 1 + 2 == 3 { 38 return Ok(()); 39 } else { 40 return Err(CustomErr::error); 41 } 42} 43 44// 函数跨越模块边界时（由其他模块调用当前函数），推荐 45fn foo() -> Result<(), i32> { 46 if 1 + 2 == 3 { 47 return Ok(()); 48 } else { 49 return Err(-(EINVAL as i32)); 50 } 51} 52``` 53 54  在**模块内部**，您既可以采用返回自定义错误enum的方式，也可以采用返回Posix错误码的方式。但是，我们推荐您在模块内部，采用返回自定义错误enum的方式，这样可以使错误处理代码更加清晰。 55 56 57## 3. 注释 58 59  DragonOS的注释风格与Rust官方的不太一样。但是，我们仍然推荐您在代码中加入尽可能多的有效注释，以便于其他人理解您的代码。并且，变量、函数等声明，遵守第一节中提到的命名规范，使其能够“自注释”。 60 61### 3.1 函数注释 62 63  函数注释应该包含以下内容： 64 65- 函数的功能 66- 函数的参数 67- 函数的返回值 68- 函数的错误处理 69- 函数的副作用或者其他的需要说明的内容 70 71  函数注释的格式如下： 72 73```rust 74/// @brief 函数的功能 75/// 76/// 函数的详细描述 77/// 78/// @param 参数1 参数1的说明 79/// @param 参数2 参数2的说明 80/// 81/// @return 返回值的说明 82``` 83 84  如果函数的返回值是`Result`类型，那么返回值应当这样进行解释： 85 86```rust 87/// @return Ok(返回值类型) 返回值的说明 88/// @return Err(错误值类型) 错误的说明 89``` 90