《简洁代码之道》总结四之简洁的注释

别给糟糕的代码加注释--------------重新写吧。

注释的恰当用法是弥补在用代码表达意图时遭遇的失败。

1、注释不能美化糟糕的代码

带有少量注释而有表达力的代码，要比有大量注释的零碎而复杂的代码像样的多。与其花时间编写解释你搞出的糟糕的代码的代码注释，不如花时间清洁那堆糟糕的代码

2、用代码来阐述

只需要创建一个描述与注释所言同一事物的函数即可。

3、好注释

真正好的注释是你想办法不去写的注释

法律信息

公司代码规范要求编写与法律有关的注释。如版权及著作权声明。

基本信息的注释

有时，用注释来提供基本信息也有其好处。如，解释了某个抽象方法的返回值：

//returns an instance of the Responder being test.

protect abstract Responder responderInstance();

但更好的方式是尽量利用函数名称传达信息，如函数命名为responderBeingTest,注释就多余了。

对意图的解释

有时，注释不仅提供了有关实现的有用信息，而且还提供了某个决定后面的意图。

阐释

有时，注释把某些晦涩难明的参数或返回值的意义翻译为某种可读的形式，也会是有用的。但更好的方法是尽量让参数或返回值本身就足够清楚。但如果参数或返回值是某个标准库的一部分，或是你不能修改的代码，帮助 阐释起含义的代码就会有用。

但是，这也会冒阐释性注释本身就不正确的风险。在写注释之前，考虑下是否还有更好的办法，然后再加倍小心地确认注释正确性。

警示

有时，用于警示其他程序员会出现某种后果的注释也是有用的。

TODO注释

TODO是一种程序员认为应该做，但是由于某些原因目前还没做的工作。但无论TODO的目的如何，都不应该是在系统中留下糟糕代码的借口。所以要定期查看，删除不再需要的。

放大

注释可用来放大某种看来不合理之物的重要性。

公共API中的javadoc

如果在编写公共API,就该为它编写良好的javadoc。

4、坏注释

大多数注释都属此类。通常，坏注释都是糟糕的代码的支撑或借口，或是对错误决策的修正，基本上等于程序员自说自话。

喃喃自语

如果只是因为觉得应该或者因为过程需要就添加注释，那就是无谓之举。如果觉得写注释，就要花必要的时间确保写出最好的注释。

任何迫使读者查看其它模块的注释，都没能与读者沟通好，不值得所费。

多余的注释

不能比代码本身提供更多的信息，没有证明代码的意义，也没有给出代码的意图或逻辑，读它并不比读代码更容易的注释就是多余注释。它不如代码精确，可能误导读者接受不精确的信息，而不是正确地理解代码。

误导性注释

循规式注释

所谓每个函数都要有javadoc或每个变量都要有注释的规矩全然是愚蠢可笑的。

日志注释

很久以前，在模块开始处创建并维护这些记录还算有道理。那时，还没有源码控制系统可用。但是，如今这种冗长的记录只会让模块变得凌乱不堪，应当全部删除。

废话注释

对于这类注释废话连篇，我们都学会了视而不见。当代码修改后，这类注释就会变为谎言一堆，应该删掉。

用整理代码的决心替代创造废话的冲动吧。你会发现自己会成为更优秀、更快乐的程序员。

可怕的废话

javadoc也可能是废话。

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

位置标记

如//Actions

这多数时候纯属无理、鸡零狗碎，理应删除

括号后面的注释

如果发现自己想标记右括号，其实应该做的是缩短函数

归属与署名

源代码控制系统是这类信息最好的归属地

注释掉的代码

源代码控制系统会为我们记住不要的代码，无需再用注释来标记，删掉即可，它丢不了，我担保。

HTML注释

如果注释将由某种工具（如javadoc）抽取出来，呈现到网页，那么该是该工具而非程序员来负责给注释加上合适的HTML标签。

非本地信息

如果一定要写注释，确保它描述了离他最近的代码。

信息过多

别在注释中添加有趣的历史性话题或者无关紧要的细节描述。

不明显的联系

注释的作用是解释未能自行解释的代码。如果注释本身还行要解释，那就太遗憾了。

函数头

短函数不需要太多描述。为只做一件事的短函数选个好名字，通常要比写函数头注释要好。

非公共代码中的javadoc

对于不打算作为公共用途的代码中如果包含javadoc就令人厌恶了。