1、注释不能美化糟糕的代码
与其花时间编写解释你搞出的糟糕的代码的注释，不如花时间清洁那堆糟糕的代码
2、用代码来阐述
通俗点说，与其写一行注释，不如创建一个与注释所言同一事物的函数
3、好注释
唯一真正好的注释是你想办法不去写的注释
3.1 法律信息
公司代码规范要求编写与法律有关的注释，如版权、著作权声明等
法律信息，不应是合同或法典，应该是指向一份标准许可或其他外部文档，而不是具体详细条款
3.2 提供信息的注释
有时用注释来提供基本信息也是有用处的
但若函数名足以描述基本信息，则上述注释就多余了
3.3 对意图的解释
一段代码的当前含义通过函数名可以表达，但是这段代码这么处理的后续意图，这时候就需要用注释来说明了
3.4 阐释
对于晦涩难明的参数或者返回值的意义，可以用注释来说明，当然如果参数和返回值命名本身已经可以阐释，则注释就多余了
当参数或者返回值是标准库的一部分，或者无法修改的代码，则此时注释则是必要的
阐释性注释本身是存在本身就不正确的风险
3.5 警示
有时，比如某段代码存在某种风险，用警示性注释提醒其他程序员是有用的
3.6 TODO注释
TODO 注释一般用来注释某段代码段是为了做啥事，但当前还没做，所以提示在优化代码的时候不要删掉了
3.7 放大
注释可以用来放大某种看来不合理之物的重要性
3.8 公共API中的Javadoc
如果在编写公共的API，就该为他编写良好的Javadoc
4、坏注释
大多数注释都属于坏注释
4.1 喃喃自语
对于一段注释，读者根本不知道注释在说啥，需要通过阅读其他相关模块代码来揣度注释的含义，这种就是代码作者在楠楠自语
4.2 多余的注释
代码已经很明确了，注释又将代码的含义描述了一遍，甚至注释描述还不如代码精确，这种注释就是多余的
4.3 误导性注释
注释与实际代码功能不一致或不完全一致，这种注释就是误导性注释
4.4 循规式注释
比如每个函数都要有Javadoc，或者每个变量都要有注释，这种规矩简直是不可接受的，遵循这种规矩的注释就称为循规式注释，让代码变得散乱，令人迷惑不解
4.5 日志式注释
没修改一次就加一次带时间戳的的注释就是日志式注释，如今的代码控制系统功能如此之强大，日志式注释已经没有任何意义了，只会让代码看上去更乱
4.6 废话注释
显而易见的，没有必要在进行注释了，比如对一个类的定义的代码，你给加一条注释“这是在定义类”，这不是废话吗
4.7 可怕的废话
4.6中描述的废话注释是说对显而易见的功能又进行描述，而这里可怕的废话是指，将代码原封不动的拷贝到注释里面
4.8 能用函数或变量时就别用注释
对一个复杂的语句进行注释，不如将其拆分为几个带有变量或函数的子句，通过变量名称或函数名称表达含义
4.9 位置标记
标记类注释，如 // Actions //////////////////////////////////////，如果用的多了，本想凸显的反而沉默在背景噪音中了，尽量少用
4.10 括号后面的注释
括号后面用注释，说明代码块结构已经嵌套的太多了，应该通过封装函数来简化代码层级了，而不是使用注释
4.11 归属和署名
源代码控制系统是这类信息最好的归属地
4.12 注释掉的代码
注释掉的代码别人不敢删，此外，历史记录可以通过源代码控制系统找回，所以如果代码不要直接删掉
4.13 HTML注释
在代码中放HTML注释是非常难读的
4.14 非本地信息
注释紧跟代码，比如切勿去写个注释，结果注释描述的是其他位置代码的功能或实现
4.15 信息过多
注释要言简意赅，不要当小说写
4.16 不明显的联系
注释和代码之间的联系应该显而易见的，如果注释都需要注释才能明白，那就太垃圾了
4.17 函数头
短函数不需要太多描述，为只做一件事的短函数选个好名字，通常要比写函数头注释更好
4.18 非公共代码中的Javadoc
Javadoc对于公共的API非常有用，但是对不打算作公共用途的代码就令人讨厌了
苏公安网备 32011402010933号