跳转至

代码规范

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

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 这种命名方式。

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

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