注释
[warning] 注释的恰当用法是弥补我们在用代码表达意图时遭遇的失败
注释不能美化糟糕的代码
- 写注释的常见动机之一就是糟糕代码的存在
- 带有少量注释的整洁而有表达力的代码，比带有大量注释的零碎而复杂的代码像样的多
代码来阐述
很多时候，简单到只需要创建一个描述与注释所言同一事物的函数即可
有些代码注释是必须的，好注释
法律信息，有可能的话指向一份许可文档或者其他外部文档
- 版权及著作权声明就是必须和有理由在每个源文件开头注释处放置的内容
- 将这些注释放到一份标准或其他外部文档
提供信息的注释，最好的方式是用函数来表达
- 对意图的解释
- 阐释，最好的方法是让参数和返回值来说明清楚
- 警示，警高后果的，有必要
- TODO注释，是有必要的，是由于某些原因没有做的内容
- 放大，放大不合理之物的重要性
- 公共api中的javadoc
坏注释
- 自言自语
- 多余的注释，名字可以解释清楚
- 误导性注释，注释不明确
- 循规式注释
- 日志式注释
- 废话注释
- 能用函数或者变量别用注释
- 位置标记××××××××××××××××××××××××××之类的
- 括号后边的注释//这是吃饭用的例如
- 归属于签名，谁写的这破玩意，没意义
- 注释掉的代码，记住，一定要删除
- html注释
- 非本地信息
- 信息过多
- 不明显的关系
- 函数头注释，不需要，取个好名字就行了
- 非公共代码中的javadoc