注释规范
别给糟糕的代码加注释——重新写吧
- 注释的恰当用法是弥补我们在用代码表达意图时遭遇的失败。
注释会撒谎
- 注释存在的时间越久，就离其所描述的代码越远。
- 代码在变动，然而注释并不总是随之变动。
写注释要记住的要点
- 注释不能美化糟糕的代码。与其花时间编写解释你写出的糟糕代码的注释，还不如清洁那些糟糕的代码。
- 用代码来阐述，使变量名更易懂。
好的注释
- 提供信息的注释。例如解释某个抽象方法的返回值，规定参数的顺序和个数。
- 对意图的解释。使别人更清楚一段复杂代码是在干什么。
- 法律信息。在每个源文件开头，写上版权时间等法律信息。
常见的注释（重要）
- 阐释。把一些难懂的参数和返回值的意义翻译成某种可读形式。
- 警示。比如说有一个函数，测试它将会花上很多时间，我们将写上警示。
- 放大重要性。就是可以用来放大某处(看起来不合理)的重要性。
- TODO，大部分ide会识别定位TODO注释。如果有写TODO的习惯，要定期查看。
坏注释
通常，坏注释都是糟糕的代码的支撑和借口，或者对错误决策的修正。
- 注释掉的代码。注释后的代码会严重误导以后别人阅读这段代码，在早已有版本控制系统的时代，系统会将之前版本的代码记录，而无需我们用注释来标记，所以被注释掉的代码应该全部删掉。
- 为了解释复杂语句的注释。当一行语句很复杂的时候，我们通常会写注释。但实际上规范的写法是，一个语句只做一件简单的事，我们应该重构原来的复杂语句，改成几行简单语句，从而代替注释。
- 喃喃自语。任何注释如果要迫使读者查看其它模块的注释和代码，就是没能与读者沟通好，这样的代码不值得去写。就像喃喃自语一样，并没有它的真正。
- 多余的注释。当注释没有证明代码的意义，也没有给出代码的意图和逻辑，它并不比读代码更容易的时候，这种注释，多半是多余的。他不如代码精确，会误导读者接受不精确的信息，而不能正确的理解代码。
- 误导性注释。有的时候注释缺少一些信息，会误导程序员，使得其他人简单的调用某个函数，哦，缺少的信息，很可能导致程序员陷入调试的困境之中。
网友评论