代码整洁之道(三)
第四章 注释
关于注释的认识和理解：
<1>什么也比不上放置良好的注释来的有用；什么也比不上乱七八槽的注释会搞坏一个模块；什么也不会比陈旧、提供错误信息的注释更具有破坏性;
<2>如果编程语言足够有表达力，那么就不需要注释；
<3>注释的恰当用法是弥补我们在用代码表达意图时遭遇的失败;
(4.1)注释不能美化槽糕的代码
写注释的常见动机之一是糟糕代码的存在。与其花时间编写解释你那糟糕代码的注释不如去清洁你那糟糕的代码;
(4.2)用代码来阐释
很多时候，简单到只需要一个描述与注释所言同一事物的函数即可;
(4.3)好注释
唯一真正好的注释是你去想办法不去写注释
<4.3.1>法律信息
有时公司代码规范要求编写与法律有关的注释;
<4.3.2>提供信息注释
这类注释有时管用，但更好的方式是利用函数名称传达信息;
<4.3.3>对意图的解释
有时注释，不仅提供了相关实现信息，还提供了某个决定后面的意图
<4.3.4>阐释
注释把某些晦涩的参数或者返回值的意义翻译为某种可读的形式也会是有用的
<4.3.5>警示
用于警告其他程序员会出现某种后果的注释
<4.3.6>ToDo注释
是一种程序员觉得应该做但是还没做的工作。应尽量的减少这种注释
<4.3.7>放大
可以用来放大某种不合理之物的重要性
<4.3.8>公共API中的Javadoc
没哟什么比良好描述的公共API更有用和令人满意的
(4.4)坏注释
大多数注释都属于此类，坏注释通常是糟糕代码的支撑或者借口抑或是错误决策的修正
<4.4.1>喃喃自语
如果你只是因为觉得或者应该过程中添加注释，那就是无谓之举了;
<4.4.2>多余的注释
<4.4.3>误导性的注释
不要写出不够精确的注释
<4.4.4>循规式注释
所谓每个函数都需要Javadoc或者每个变量都需要注释的规矩全然是可笑的。
<4.4.5>日志式注释
这种冗长的记录只会让模块变得凌乱不堪，应当全部删除
<4.4.6>废话注释
<4.4.7>可怕的废话
<4.4.8>能用函数或者是变量时就别用注释
<4.4.9>位置标记
少用标记栏
<4.4.10>括号后面的注释
如果发现自己想标记右括号，那么请思考如何缩短函数
<4.4.11>归属与签名
源代码控制系统非常善于记住是谁何时修改了什么内容，没有必要用那些小小的签名污染了你的代码
<4.4.12>注释掉的代码
直接把代码注释掉是非常讨厌的做法，删除它
<4.4.13>HTML注释
HTML的注释是一种厌物
<4.4.14>非本地信息
假如你一定要写注释，请确保它描述了离他最近的代码
<4.4.15>信息过多
不要扯一些不相关的信息
<4.4.16>不明显的联系
如果注释本身还需要解释，那就太遗憾了
<4.4.17>函数头
为只做一件事的段函数起个好名字，比写函数头要好得多
<4.4.18>非公共代码中的Javadoc
对于不打算作为公共代码的函数的javadoc就会变得厌恶了
