1、别给糟糕的代码加注释----重新写吧
2、注释的恰当用法是弥补我们在用代码表达意图时遭遇的失败。注释总是一种失败。我们总无法找到不要注释就能表达自我的方法,所以总要有注释,这并不值得庆贺。
3、如果你发下自己需要写注释,再想想看是否有办法翻盘,用代码来表达。每次用代码表达,你都该夸奖一下自己。每次写注释,你都该做个鬼脸,感受自己在表达能力上的失败。
4、注释会撒谎,也不是说总是如此或有意如此,但出现得是在太频繁,注释存在的时间越久,就离其所描述的代码越远,越来越变得全然错误。原因很简单。程序员不能坚持注释。
5、代码在变动,在演化。从这里移到这里。彼此分离、重造又合到一处。很不幸,注释并不总是随之变动。注释常常会与其所描述的代码分隔开来,孑然飘零,越来越不准确。
6、写注释的常见动机之一是糟糕的代码的存在。我们编写一个模块,发现他令人困扰、乱七八糟。我们知道,它烂透了。我们告诉自己:“喔,最好写点注释。”不!最好是把代码弄干净。
7、带有少量注释的整洁而有表达力的代码,要比带有大量注释的零碎而复杂的代码像样得多。与其花时间编写解释你搞出的糟糕的代码的注释,不如花时间清洁那堆糟糕的代码。
8、有时,代码本身不足以解释其行为,但是很多时候,简单到只需创建一个描述与注释所言同一事物的函数即可。
9、有些注释是必须的,也是有利的。不过,唯一真正好的注释是你想办法不去写的注释。
10、有时,公司代码规范要求编写与法律有关的注释。这类注释不应是合同或法典。只要有可能,就指向一份标准许可或其他外部文档,而不要把所有条款放到注释中。
11、有时,注释不仅提供了有关实现的有用信息,而且还提供了某个决定后面的意图。
12、有时,注释把某些晦涩难明的参数或返回值的意义翻译为某种可读形式,也会是有用的。通常,更好的方法是尽量让参数或返回值自身就足够清楚;但如果参数或返回值是某个标准库的一部分,或是你不能修改的代码,帮助阐释其含义的代码就会有用。当然,这也会冒阐释性本身就不正确的风险。所以,再写这类注释之前,考虑一下是否还有更好的办法,然后再加倍小心地确认注释的正确性。
13、有时,用于警告其他程序员会出现某种后果的注释也是有用的。当然,现在我们多数会利用符合恰当解释性字符串的@Ignore属性来关闭测试用例。比如当@Ignore(“Takes too long to run ”)。但在JUnit4之前的日子里,惯常的做法是在方法名前面加上下划线。
14、有时,有理由用//TODO形式在源码中放置要做的工作列表。TODO是一种程序员认为应该做,但是由于某些原因目前还没做的工作。它可能是要提醒删除某个不必要的特性,或者要求他人注意某个问题。它可能是恳请别人取个好名字,或者提示对依赖某个计划事故的修改。无论TODO的目的如何,它都不是在系统中留下糟糕的代码的借口。
15、如今,大多数好IDE都提供了特别的手段来定位所有TODO注释,有些注释看来丢不了。你不会愿意代码因为TODO的存在而变成一堆垃圾,所以要定期查看,删除不再需要的。
16、注释可以用来放大某种看来不合理之物的重要性。
17、没有什么比被良好描述的公共API更有用和令人满意的了。标准java库中的javadoc就是一例。没有它们,写java程序就会变得很难。
18、如果你在编写公共API,就该为它编写良好的javadoc。不过,就像其他注释一样,javadoc也可能误导、不适用或者提供错误信息。
19、大多数注释都属于坏注释一类。通常坏注释都是糟糕的代码的支撑或借口,或者对错误决策的修正,基本上等于程序员自说自话。
20、如果只是因为你觉得应该或者因为过程需要就添加注释,那就是无谓之举。如果你决定写注释,就要花必要的时间雀斑写出最好的注释。
21、我们唯有检视系统其它部分的代码,弄清事情原委。任何迫使读者查看其它模块的注释,都没能与读者沟通好,不值所费。
22、如果一段注释,并不能比代码本身提供更多的信息,它没有证明代码的意义,也没有给出代码的意图或逻辑,那么这段代码就是多余的注释。读它并不比读代码更容易。事实上,它不如代码精确,误导读者接受不精确的信息,而不是正确的理解代码。
23、有时,尽管初衷可嘉,程序员还是会写出不够精确的注释。这些注释就是误导性注释。
24、所谓每个函数都要有javadoc或每个变量都要有注释的规矩全然是愚蠢可笑的。这类注释徒然让代码变得散乱,满口胡言,令人迷惑不解,这就是循规式注解。
25、有人会在每次编辑代码时,在模块开始处添加一条注释。这类注释就像是一种记录每次修改的日志。很久以前,在模块开始处创建并维护这些记录还算有道理。那时,我们还没有源码控制系统可用。如今,这种冗长的记录只会让模块变得凌乱不堪,应当全部删除。
26、有一些废话注释,在最初时我们会视而不见,可是最终当代码修改之后,这类注释就变做了谎言一堆。与其纠缠于毫无价值的废话注释,程序员应该意识到,挫败感可以由改进代码结构而消除,应该把力气放在整理代码上而不是创造废话的注释上。
27、javadoc也可能是废话,
28、能用函数或变量是就别用注释。
29、有时候,程序员喜欢在源代码中标记某个特别位置。把特定函数趸(dun)放在这种注释的标记栏下面,多数时候实属无理。鸡零狗碎,理当删除。如果标记栏不多,就会显而易见。所以尽量少用标记栏,只在特别有价值的时候用。如果滥用标记栏,就会沉没在噪音中,被忽略掉。
30、有时,程序员会在括号后面放置特殊的注释。尽管这对于含有深度嵌套结构的长函数可能有意义,但只会给我们更愿意编写的短小、封装的函数带来混乱。如果你发现自己想标记右括号,其实应该做的是缩短函数。
31、源代码控制系统非常善于记住是谁在何时添加了什么恶。没必要用那些小小的签名搞脏代码。你也许会认为,这种注释大概有助于他人了解应该和谁讨论这段代码。不过,事实却是注释放在那儿一年又一年,越来越不准确,越来越和原作者没关系。
32、直接把代码注释掉是讨厌的做法,别这么干。其他人不敢删除注释掉的代码。他们会想,代码依然放在那儿,一定有其原因,而且这段代码很重要,不能删除。注释掉的代码堆积在一起,就像破酒瓶底的渣滓一般。20世纪60年代,曾经有那么一段时间,注释掉的代码可能有用。但是我们已经拥有优良的源代码控制系统如此之久,这些系统可以为我们记住不要的代码。我们无需再用注释来标记,删除即可,他们丢不了。
33、源代码注释中的HTML标记是一种厌物,如果注释将由某种工具抽取出来,呈现到网页,那么该是工具而非程序员来负责给注释加上合适的HTML标签。
34、加入你一定要写注释,请确保它描述了离它最近的代码。别在本地注释的上下文环境中给出系统级的信息。
35、别在注释中添加有趣的历史性话题或者无关的细节描述。
36、注释及其描述的代码之间的联系应该显而易见。如果你不嫌麻烦要写注释,至少让读者能看着注释和代码,并且理解注释所谈何物。
37、短函数不需要太多描述。为只做一件事的短函数选个好名字,通常要比写函数头注释要好。
38、虽然javadoc对于公共API非常有用,但对于不打算作公共用途的代码就令人厌恶了。为系统中的类和函数生成javadoc页面并非总有用,而javadoc注释额外的形式要求机会等同于八股文章。
* 以上内容是看《代码整洁之道》[美·马丁] 第四章 注释 的总结