第四章 注释

第四章 注释

---

4.1 注释不能美化的代码

• 不用注释，重新写；

4.2 用代码来阐述

• 简单的代码不一定能够解释其本身，给其起一个恰当的函数名称更好；

//check to see if the employee is eligible for full benefits
if ((emloyee.flags & HOURLY_FLAG)&&(emlpoyee.age>65))
//优化
if(employee.isEligibleForFullBenefits())

4.3 好注释

4.3.1 法律信息

• 在源文件的开头之处放置法律信息，该信息指向一个标准许可或者外部文件，不要写入全部写入文件

4.3.2 提供信息的注释

• 注释能够提供有用的信息
• 起一个好的函数名称可以不用添加注释

4.3.3 对意图的解释

• 对于一段有目的的代码，在开始处给出其解释

4.3.4 阐释

• 将晦涩难懂的参数或语句解释清楚，但存在注释错误的风险，所以在书写这类的注释时，要确保注释的正确性；

assertTrue(a.compareTo(a) == 0); // a==a  当代码改变或者复制时，不能确保及时更改注释，难以确保注释的真确性；

4.3.5 警示

• 用于警示某些代码会出现某种后果，此类注释十分必要，例如代码段将耗费大量时间，或者代码并非线程安全的

4.3.6 TODO注释

• //TODO- 类注释用于在源代码中要做的工作列表；该函数可能还没有实现，但功能应在TODO注释中表明

4.3.7 放大

• 用来放大某些看似不合理处的重要性，着重提醒重要之处

4.4 坏注释

4.4.1 喃喃自语

• 不要因为你觉得要就去写注释，代码需要才是真的需要；
• 写注释就要花时间去写出最好的注释
  
  • 下面代码中的注释没有解释清楚默认加载是何时间进行的

public void loadProperties(){
    try{
        ....
    }
    catch(IOException e){
     //No properties files means all defaults are loaded
    }
}

4.4.2 多余的注释

• 当注释不能够比代码提供更多的信息时，注释纯属多余；
• 好的注释给出代码的意图、逻辑、意义；

4.4.3 误导性注释

• 注释写的不够精确，产生误导性；

4.4.4 循规式注释

• 不是每一个函数都要有注释，否则只会扰乱代码的整洁性；

4.4.5 日志式注释

• 现在利用版本控制系统可以完全避免;

4.4.6 废话式注释

• 有些插件自动生成的废话注释要删除，例如表明是构造函数的插件；

4.4.7 可怕的废话

• 避免无用的废话；
• 注意粘贴时修改；

4.4.8 能用函数或变量时就别用注释

• 取合适的函数名称代替注释；

4.4.9 位置标记

• 利用//Actions//此类函数分类的标记时，并且分类不多时，往往会淹没在代码中；

4.4.10 括号后面的注释

try{
……
}//try
catch{
……
}//catch

• 当觉得需要添加此类注释时，表明函数过长了，需要重构

4.4.11 归属与署名

• 没有必要，版本控制系统会添加

4.4.12 注释掉的代码

• 不要直接注释掉代码，在其他人眼中，不知道是否可以删除注释的代码
• 需要注释掉的代码直接删除，利用版本控制系统可以方便找回；

4.4.13 HTML注释

• 没有必要

4.4.14 非本地信息

• 注释一定要与代码靠近，否则函数可能修改，但注释没有修改

4.4.15 信息过多

• 没有必要在注释中添加无关细节描述；

4.4.16 不明显的联系

• 注释与代码之间的联系应该显而易见；

/*
* start with an array that is big enough to hold all the pixels
* (plus filter bytes), and an extra 200 bytes for header info
*/
this.pngBytes = new byte[((this.width + 1) * this.heigh * 3) + 200];

• 该段注释中没有阐述fliter为何物
• 1、3在语句中有和中意思
• 为何选取200
• 注释本身还需注释，就是不合格的注释

4.4.17 函数头

• 短函数无需太多描述，直接取一个好的名字