跳转至

代码规范

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

Git

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

代码风格

保证代码的简洁：

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

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

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

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

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

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

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

对于比较复杂的逻辑流程，不应该把代码都写在一个函数中，而是应该拆分成多个函数，以及 struct 或 enum 的方法。

对于比较复杂的程序，不应该把代码都写在一个源代码文件中，而是按照功能拆分成多个模块，可以参考 Defining Modules to Control Scope and Privacy。（在第一次大作业中，因为课上还没讲到 Rust 的模块组织，不会在这里扣分。）

为了保证代码的规范性，可以使用一些工具自动进行检查和修复：

  • 可以用 rustfmt 或者 cargo fmt 格式化代码
  • 可以用 cargo clippy 发现代码中不规范、可以优化的地方

更详细的使用说明可以参考开发辅助工具。

强烈建议在 IDE 中启用自动代码格式化和 clippy 检查。如果依赖于手动运行命令，甚至在 push 到 GitLab 后再查看 CI 结果，一方面会更加麻烦，一方面也可能导致 Git 历史记录中出现不规范的代码和仅用于修复规范性问题的额外 commit。