代码注释规范

本文描述了 MatrixOne 所使用的代码注释的规范和样式。当你提交代码时，请务必遵循已有的代码注释规范。

为什么注释很重要？

  • 加快了代码审查流程
  • 有助于维护代码
  • 提高 API 文档的可读性
  • 提高整个团队的开发效率

什么时候需要注释？

以下类型的代码时很有必要做出注释：

  • 关键性代码
  • 艰深晦涩的代码
  • 复杂却有趣的代码
  • 如果代码存在错误但您无法修复，或者只想暂时忽略
  • 如果代码并非最优，但你现在没有更好的方法
  • 提醒自己或其他人代码中存在缺失的功能或即将开发的功能

以下部分也需要进行注释：

  • Package (Go)
  • File
  • Type
  • Constant
  • Function
  • Method
  • Variable
  • Typical algorithm
  • Exported name
  • Test case
  • TODO
  • FIXME

如何进行注释？

格式

  • Go

  • 使用 // 来进行单行注释

  • 使用 /* ... */ 对代码块进行注释
  • 使用 gofmt 来格式化你的代码
  • 把单行注释、代码块注释放在代码上方
  • 折叠多列注释
  • 注释中的每行文本不超过 100 个词

  • 包含 URL 的注释：

  • 如果文本链接到同一个 GitHub 存储库中的文件，则使用 relative URL，

  • 如果带有此注释的代码是从另一个存储库复制来的，则使用 absolute URL，

语言

  • 单词

  • 请统一使用美式英语

    • color, canceling, synchronize (推荐)
    • colour, cancelling, synchronise (不推荐)
    • 注意拼写正确

    • 使用标准或官方的大写

    • MatrixOne, Raft, SQL (正确)

    • matrixone, RAFT, sql (错误)

    • 使用一致性的短语和词汇

    • “dead link” vs. “broken link”（在一篇文章或文件中只能出现其中一个）

    • 不要使用冗长的复合词
    • 尽量不使用缩写
    • 用 We 用来代指作者和读者
    • 句子

  • 使用标准的语法和标点符号

  • 尽量使用短句

  • 句子首字母大写，并以句号结尾

  • 如果一个小写的标识符位于句子开头，可以不用大写

    1. // enterGame causes Players to enter the 2. // video game, which is about a romantic 3. // story in ancient China. 4. func enterGame() os.Error { 5. ... 6. } - 当注释用来描述代码时，应该保证使用描述性语句而非祈使句

  • Opens the file (正确)

  • Open the file (错误)

  • 使用 “this” 而非 “the” 来指代当前事物

  • Gets the toolkit for this component (推荐)

  • Gets the toolkit for the component (不推荐)

  • 允许使用 Markdown 语法格式

  • Opens the log file

Tips

  • 尽量在写代码的同时就完成注释，减少事后返工
  • 不要假设代码是不证自明的
  • 对于简单代码尽量避免使用过多注释
  • 有“代入感”地做注释（仿佛在进行对话一般）
  • 确保及时更新注释
  • 保证注释清楚易懂

感谢您的贡献！