跳转至

代码规范

本页面列举了一些常见的代码规范要求。

Git

  • 每个提交都应该有一定的意义，例如实现了新功能，修复了一个问题，定义了新的函数；
  • 比较复杂的程序，要边开发边提交，而不是写完了再一次性提交；
  • 不强求线性历史， 不允许使用 force push。
  • 简单明了地描述这个提交的内容；
  • 建议用英文写，用中文写也可以；
  • 不要编写的过于详细或过于简略；
  • 可以采用一些格式，例如 Conventional Commits；
  • 不掺杂个人情绪；
  • 用户名和邮箱应该配置成自己的真实姓名和邮箱；
  • 可以添加一些 Emoji。gitmoji 为提交说明中使用的 Emoji 提出了一些建议，可以参考。

代码风格

保证代码的简洁：

  • 有整齐的缩进，建议用空格缩进而非 tab，两个空格或者四个空格作为一级缩进都可以；
  • 每一行不要有太多字符，例如不超过 80 / 100 个字符；
  • 减少硬编码和魔法数字（magic number），例如代码中多次出现 3.14 的时候，应该定义 pi = 3.14，然后后面都用 pi 来指代。

在代码中编写适当的注释：

  • 在比较复杂的代码块前，描述代码的功能；
  • 过于简单的代码，一般不写注释；
  • 函数要编写注释，包括其功能，参数和输出；
  • 建议用英文，中文也可以，但是注意要用 UTF-8 编码。
  • 遵循 Rustdoc 的约定

代码中应该有适当的空格和空行：

  • 函数中，实现不同功能的代码间需要添加空行；
  • 操作符前后应该有空格，例如 c = a + b；
  • 保持前后一致的风格。

变量的命名，应该符合一定的规范：

  • 符合课件中的变量命名规范；
  • 尽量用英文单词，而不是中文拼音首字母；
  • 命名与上下文要相关；
  • 不用类似 a, b, c, d 这种命名方式。

对于比较复杂的程序，不应该把代码都写在一个源代码文件中，而是按照功能拆分成多个模块，可以参考 Defining Modules to Control Scope and Privacy。

为了实现上面的部分要求，可以采用一些自动化工具：

  • 编辑器自带的格式化功能
  • 可以用 rustfmt 或者 cargo fmt