diff --git a/docs/community/code_contribution/coding-style.md b/docs/community/code_contribution/c-coding-style.md similarity index 91% rename from docs/community/code_contribution/coding-style.md rename to docs/community/code_contribution/c-coding-style.md index 0cae2bfb..4ae2dff5 100644 --- a/docs/community/code_contribution/coding-style.md +++ b/docs/community/code_contribution/c-coding-style.md @@ -1,8 +1,8 @@ -# 代码风格 +# C语言代码风格 -  这份文档将会简要的介绍DragonOS的代码风格。每个人的代码风格都各不相同,这是一件非常正常的事情。但是,对于一个开源项目的可维护性而言,我们希望制定一些代码规范,以便包括您在内的每个开发者都能在看代码的时候更加舒服。一个充斥着各种不同代码风格的项目,是难以维护的。 +  这份文档将会简要的介绍DragonOS的C语言代码风格。每个人的代码风格都各不相同,这是一件非常正常的事情。但是,对于一个开源项目的可维护性而言,我们希望制定一些代码规范,以便包括您在内的每个开发者都能在看代码的时候更加舒服。一个充斥着各种不同代码风格的项目,是难以维护的。 -  我们在这里提出一些建议,希望您能够尽量遵循这些建议。这些建议与Linux的代码规范相似,但又略有不同。 +  我们在这里提出一些建议,希望您能够尽量遵循这些建议。这些建议与Linux的代码规范相似,但又略有不同。在变量命名上,DragonOS采用Linux的风格;对于缩进,DragonOS采用Microsoft风格。 diff --git a/docs/community/code_contribution/index.rst b/docs/community/code_contribution/index.rst index 5c132320..8eeeb7cc 100644 --- a/docs/community/code_contribution/index.rst +++ b/docs/community/code_contribution/index.rst @@ -10,4 +10,5 @@ :maxdepth: 1 the-development-process - coding-style + c-coding-style + rust-coding-style diff --git a/docs/community/code_contribution/rust-coding-style.md b/docs/community/code_contribution/rust-coding-style.md new file mode 100644 index 00000000..7de75cf4 --- /dev/null +++ b/docs/community/code_contribution/rust-coding-style.md @@ -0,0 +1,89 @@ +# Rust语言代码风格 + +  这篇文档将会介绍DragonOS中的Rust语言代码风格。随着开发的进行,这些风格可能会发生变化,但是我们会尽量保持风格的一致性。 + +## 1. 命名 + +  这部分基于Rust语言圣经中的[命名规范](https://course.rs/practice/naming.html)进行修改,本文未提及的部分,请参考Rust语言圣经中的[命名规范](https://course.rs/practice/naming.html)。 + +## 2. 格式 + +### 2.1 缩进 + +  请在提交代码之前,使用`cargo fmt`命令对代码进行格式化。 + +### 2.2 函数返回值 + +  尽管Rust可以返回函数的最后一行的语句的值,但是,这种方式会使代码的可读性变差。因此,我们推荐您在函数的最后一行使用`return`语句,而不是直接返回值。 + +```rust +// 不推荐 +fn foo() -> i32 { + 1 + 2 +} + +// 推荐 +fn foo() -> i32 { + return 1 + 2; +} +``` +### 2.3 错误处理 + +  DragonOS采用返回Posix错误码作为**模块间错误处理**的方式。为了确保在模块之间,错误处理代码的一致性,我们推荐在发生错误的时候,返回`Err(i32)`,并且posix错误码的值应当是负数。这样做的优点尤其体现在跨模块调用函数时,可以直接返回错误码,从而降低错误处理代码的耦合度。 + +```rust +// 函数跨越模块边界时(由其他模块调用当前函数),不推荐 +fn foo() -> Result<(), CustomErr> { + if 1 + 2 == 3 { + return Ok(()); + } else { + return Err(CustomErr::error); + } +} + +// 函数跨越模块边界时(由其他模块调用当前函数),推荐 +fn foo() -> Result<(), i32> { + if 1 + 2 == 3 { + return Ok(()); + } else { + return Err(-(EINVAL as i32)); + } +} +``` + +  在**模块内部**,您既可以采用返回自定义错误enum的方式,也可以采用返回Posix错误码的方式。但是,我们推荐您在模块内部,采用返回自定义错误enum的方式,这样可以使错误处理代码更加清晰。 + + +## 3. 注释 + +  DragonOS的注释风格与Rust官方的不太一样。但是,我们仍然推荐您在代码中加入尽可能多的有效注释,以便于其他人理解您的代码。并且,变量、函数等声明,遵守第一节中提到的命名规范,使其能够“自注释”。 + +### 3.1 函数注释 + +  函数注释应该包含以下内容: + +- 函数的功能 +- 函数的参数 +- 函数的返回值 +- 函数的错误处理 +- 函数的副作用或者其他的需要说明的内容 + +  函数注释的格式如下: + +```rust +/// @brief 函数的功能 +/// +/// 函数的详细描述 +/// +/// @param 参数1 参数1的说明 +/// @param 参数2 参数2的说明 +/// +/// @return 返回值的说明 +``` + +  如果函数的返回值是`Result`类型,那么返回值应当这样进行解释: + +```rust +/// @return Ok(返回值类型) 返回值的说明 +/// @return Err(错误值类型) 错误的说明 +```