代码注释规范
本文描述了 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 用来代指作者和读者
-
-
句子
- 使用标准的语法和标点符号
- 尽量使用短句
-
句子首字母大写,并以句号结尾
-
如果一个小写的标识符位于句子开头,可以不用大写
// enterGame causes Players to enter the // video game, which is about a romantic // story in ancient China. func enterGame() os.Error { ... }
-
-
当注释用来描述代码时,应该保证使用描述性语句而非祈使句
- 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
- Opens the
Tips
- 尽量在写代码的同时就完成注释,减少事后返工
- 不要假设代码是不证自明的
- 对于简单代码尽量避免使用过多注释
- 有“代入感”地做注释(仿佛在进行对话一般)
- 确保及时更新注释
- 保证注释清楚易懂
感谢您的贡献!