第四章 注释
什么也比不上放置良好的注释来得有用。什么也不会比乱七八糟的注释更有本事搞乱一 个模块。什么也不会比陈旧、提供错误信息的注释更有破坏性。
注释的恰当用法是弥补我们在用代码表达意图时遭遇的失败。注意,我用了“失败”一 词。我是说真的。注释总是一种失败。我们总无法找到不用注释就能表达自我的方法,所以总要有注释,这并不值得庆贺。
如果需要注释,就要想办法,能不能不要注释,使用代码去表达。注释出现太频繁,出现的时间越久,就离所描述的代码越远,因为代码一直在变动,而注释不一定跟着变动。
只有代码能忠诚的告诉我们,他做了什么事情,唯一准确的信息来源,尽管有时候我们需要添加注释,但是我们应该多花心思去减少注释。
注释并不能美化代码
写注释的原因之一就是糟糕的代码存在。
带有少量注释的整洁而有表达力的代码,要比带有大量注释的零碎而复杂的代码像样得 多。与其花时间编写解释你搞出的糟糕的代码的注释,不如花时间清洁那堆糟糕的代码。
用代码来阐述
4.3 好注释
有些注释是必须的,也是有利的。
4.3.1 法律信息
有时,公司代码规范要求编写与法律有关的注释。例如,版权及著作权声明就是必须和 有理由在每个源文件开头注释处放置的内容。
4.3.2 提供信息的注释
有时,用注释来提供基本信息也有其用处,例如使用注释解释抽象方法的返回值
4.3.3 对意图的解释
有时,注释不仅提供了有关实现的有用信息,而且还提供了某个决定后面的意图。
4.3.4 阐释
有时,注释把某些晦涩难懂的参数或返回值的意义翻译为某种可读形式,也许是有用的。当然,更好的方法是尽量让参数或返回值足够清楚,如果参数、返回值是某个标准库或是你不能修改的,写个注释是有用的。
4.3.5 警示
用于警告其他程序员会出现某种后果的注释也是有用的。
例如,下面的注释解释了为什么要关闭某个特定的用例
4.3.6 TODO注释
TODO是一种程序员认为应该做,但由于某些原因目前还没做的工作。它可能是要提醒删除某个不必要的特性,或者要求他人注意某个问题。它可能是恳请别人取个好名字,或者提示对依赖于某个计划事件的修改。无论TODO的目的如何,它都不是在系统中留下糟糕的代码的借口。
大多数好IDE都提供了特别的手段来定位所有TODO注释。
4.3.7 放大
注释可以用来放大某种看来不合理之物的重要性。
4.3.8 公共API中的Javadoc
没有什么比被良好描述的公共API更有用和令人满意的了。标准Java库中的Javadoc 就是一例。没有它们,写Java程序就会变得很难。
如果你在编写公共API,就该为它编写良好的Javadoc 。不过要记住本章中的其他建议。 就像其他注释一样,Javadoc 也可能误导、不适用或者提供错误信息。
4.4 坏注释
大多数注释都属此类,通常,坏注释都是糟糕的代码的支撑或接口,或者对错误决策的修正,基本上等于程序员的自说自话。
4.4.1 喃喃自语
如果只是你觉得需要加注释或者因为过程需要加注释,那就是无畏之举,写注释也是要花时间写出好注释。
4.4.2 多余的注释
4.4.3 误导的注释
尽管初衷可嘉,但是想4-1那种代码会有误导嫌疑的注释。
有些细微的误导信息,可能会比代码本身更难阅读,也有可能会导致程序员使用错误。
4.4.4 询规式注释
如果每个函数、字段都要有javadoc或者注释这些规则是可笑的。因为很可能像4-3那样,废话的注释,还可能误导读者。
4.4.5 日志式注释
有人会在每次编辑代码时,在模块开始处加一条注释,这类注释就像是一种记录每次修改的日志,有些是类似日志的代码模块。
4.4.6 废话式注释
有些注释是废话,喋喋不休。
4.4.7 可怕的废话
4.4.8 能用函数或变量时就别用注释
4.4.9 位置标记
有时候,程序员喜欢在源代码里标记某个特别的代码。
// Actions //
这种标记就像噪音一样
4.4.10 括号后面的注释
有时,程序员会在括号后面加特殊的注释,如代码清单4-6所示,尽管这对于含有深度结构的长函数可能有意义,但只会给我们愿意写短小、封装的函数带来混乱
4.4.11 归属与署名
// Added by Rick
源代码控制系统非常善于记住是谁在何时添加了什么,写这种小签名会弄脏代码,时间久了之后,别人可能也修改了,和原作者就没有关系了。
4.4.12 注释掉的代码
直接把代码注释掉,是很讨厌的。
4.4.13 HTML注释
源代码注释中的HTML标记是一种厌物,有时候可能会因为HTML注释而变得难以阅读。
如果注释将由某种工具(例如javadoc)抽取出来,呈现到网页上,那么应该是工具而非程序员给注释加上HTML标签。
4.4.14 非本地信息
假如你一定要写注释,请确保它描述了离它最近的代码。别在本地注释的上下文环境中给出系统级的信息。
4.4.15 信息过多
别在注释中添加有趣的历史性话题或者无关的细节描述
4.4.16 不明显的联系
注释及其描述的代码之间的联系应该显而易见。如果你不嫌麻烦要写注释,至少让读者能看着注释和代码,并且理解注释所谈何物。
4.4.17 函数头
短函数不需要太多描述。为只做一件事的短函数选个好名字,通常要比写函数头注释要好。
4.4.18 非公共代码中的javadoc
虽然Javadoc 对于公共API非常有用,但对于不打算作公共用途的代码就令人厌恶了。 为系统中的类和函数生成Javadoc 页并非总有用,而Javadoc 注释额外的形式要求几乎等同于 八股文章。