代码注释规范

comments_style.md

代码注释规范

标点, 拼写和语法

注释的通常写法是包含正确大小写和结尾句号的完整语句. 短一点的注释 (如代码行尾注释) 可以随意点, 依然要注意风格的一致性. 完整的语句可读性更好, 也可以说明该注释是完整的, 而不是一些不成熟的想法.

虽然被别人指出该用分号时却用了逗号多少有些尴尬, 但清晰易读的代码还是很重要的. 正确的标点, 拼写和语法对此会有所帮助.

Tag注释

以 TODO tag为例

TODO 注释要使用全大写的字符串 TODO, 在随后的圆括号里写上你的大名, 邮件地址, 或其它身份标识. 冒号是可选的. 主要目的是让添加注释的人 (也是可以请求提供更多细节的人) 可根据规范的 TODO 格式进行查找. 添加 TODO 注释并不意味着你要自己来修正.

// TODO(z@augmn.com): Use a "*" here for concatenation operator.
// TODO(skyjia) change this to use relations.

如果加 TODO 是为了在 “将来某一天做某事”, 可以附上一个非常明确的时间 (“Fix by November 2005”), 或者一个明确的事项 (“Remove this code when all clients can handle JSON responses.”).

Tag类型

• TODO: 如果代码中有该标识，说明在标识处有功能代码待编写，待实现的功能在说明中会简略说明。

  // TODO(Jack): implement the foo module here

• XXX: 如果代码中有该标识，说明标识处代码虽然实现了功能，但是实现的方法有待商榷，希望将来能改进，要改进的地方会在说明中简略说明。

  // XXX: performance leaks here. Should improve with an O(N) algorithm instead.
  
  // XXX: Due to a bug in package `zzz`, we have to warp method foo() here as a tricky hack.

• FIXME: 如果代码中有该标识，说明标识处代码需要修正，甚至代码是错误的，不能工作，需要修复，如何修正会在说明中简略说明。

  // FIXME: Due to a bug in package `xxx`, we have to warp method foo() here as a tricky hack.
  
  // FIXME: Fix bug at https://github.com/augmn/issues-engineer/issues/2194

弃用注释

通过弃用注释（DEPRECATED comments）以标记某接口点（interface points）已弃用。

可以写上包含全大写的 DEPRECATED 的注释，以标记某接口为弃用状态。注释可以放在接口声明前，或者同一行。

在 DEPRECATED 一词后，留下您的名字，邮箱地址以及括号补充。

// DEPRECATED: won't be supported since version 4.1.0 due to changes on response message.