注释

由 Loen 创建, 最后一次修改 2016-02-24

良好的代码是最佳的文档。当你要加一个注释时,扪心自问,“如何改善代码让它不需要注释?” 改善代码,再写相应文档使之更清楚。
——Steve McConnell

  • 编写让人一目了然的代码然后忽略这一节的其它部分。我是认真的!
  • 用英语写注释。
  • # 与注释文字之间使用一个空格。
  • 注释超过一个单词了,应句首大写并使用标点符号。句号后使用一个空格
  • 避免肤浅的注释。

    # 差
    counter += 1 # 计数器加一
  • 及时更新注释。过时的注解比没有注解还差。

好代码就像是好的笑话 - 它不需要解释 
——Russ Olsen

  • 避免替烂代码写注释。重构代码让它们看起来一目了然。(要嘛就做,要嘛不做——不要只是试试看。——Yoda)

注解

  • 注解应该直接写在相关代码那行之前。
  • 注解关键字后面,跟着一个冒号及空格,接着是描述问题的文字。
  • 如果需要用多行来描述问题,后续行要放在 # 号后面并缩排两个空格。

    def bar
      # FIXME: 这在 v3.2.1 版本之后会异常崩溃,或许与
      #   BarBazUtil 的版本更新有关
      baz(:quux)
    end
  • 在问题是显而易见的情况下,任何的文档会是多余的,注解应放在有问题的那行的最后,并且不需更多说明。这个用法应该是例外而不是规则。

    def bar
      sleep 100 # OPTIMIZE
    end
  • 使用 TODO 标记以后应加入的特征与功能。

  • 使用 FIXME 标记需要修复的代码。
  • 使用 OPTIMIZE 标记可能影响性能的缓慢或效率低下的代码。
  • 使用 HACK 标记代码异味,即那些应该被重构的可疑编码习惯。
  • 使用 REVIEW 标记需要确认其编码意图是否正确的代码。举例来说:REVIEW: 我们确定用户现在是这么做的吗?
  • 如果你觉得恰当的话,可以使用其他定制的注解关键字,但别忘记录在项目的 README 或类似文档中。
W3Cschool app 编程微课功能上线
二维码
建议反馈
二维码