《代码整洁之道》——（3）注释
目录
3.1、注释不能美化糟糕的代码
写注释的常见动机之一是糟糕的代码的存在。我们编写一个模块，发现它令人困扰、乱七八糟。我们知道，它烂透了。我们告诉自己：“喔，最好写点注释！”不！最好把代码弄干净！
带有少量注释的整洁而有表达力的代码，要比带有大量注释的零碎而复杂的代码像样的多。与其花时间编写解释你搞出得糟糕的代码的注释。不如花些时间清洁那堆糟糕的代码。
3.2、用代码来阐述
有时，代码本身不足以解释其行为。很多时候，简单到只需要创建一个描述与注释所言同一事物的函数即可。
3.3、好注释
有些注释是必须的，也是有利的，
3.3.1、法律信息
有时，公司代码规范要求编写法律有关的注释。例如，版权及著作权声明就是必须和有理由在每个源文件开头注释处放置的内容。
3.3.2、提供信息的注释
有时，用注释来提供基本信息也有用处。例如，注释解释某个抽象方法的返回值。这类注释有时管用，但更好的方式是尽量利用函数名称传达信息。
3.3.3、对意图的解释
有时，注释不仅提供了有关实现的有用信息，而且还提供了某个决定后面的意图。
3.3.4、阐释
有时，注释把某些晦涩难明的参数或返回值得意义翻译为某种可读形式，也会是有用的。通常，更好的方法是尽量让参数或返回值自身就足够清楚；但如果参数或返回值是某个标准库的一部分，或是你不能修改的代码，帮助阐释其含义的代码就会有用。
当然，这也会冒阐述性注释本身就不正确的风险。
3.3.5、警示
有时，用于警告其他程序员会出现的后果的注释也是有用的。
3.3.6、TODO注释
有时，有理由用//TODO形式在源代码中放置要做的工作列表。、
TODO是一种程序员认为应该做，但由于某些原因目前还没做的工作。它可能是要提醒删除某个不必要的特性，或者要求他人注意某个问题。它可能是恳请别人取个好名字，或者对依赖于某个计划事件的修改
。无论TODO的目的如何，他都不是在系统中留下糟糕代码的借口。
3.3.7、放大
注释可以用来放大某种看来不合理之物的重要性。
3.4、坏注释
3.4.1、喃喃自语
如果只是因为你觉得应该或者因为过程需要就添加注释，那就是无谓之举。如果你决定写注释，就要花必要的时间确保写出最好的注释。
3.4.2、多余的注释
3.4.3、误导性注释
有时，尽管初衷可嘉，程序员还是会写出不够精确的注释。
3.4.4、循规式注释
所谓每个函数都要有Javadoc或每个变量都要有注释的规矩全然是愚蠢可笑的。这类注释突然让代码变得混乱，满口胡言，令人迷惑不解。
3.4.5、废话注释
有时，你会看到纯然是废话的注释。它们对于显然之事喋喋不休，毫无新意。与其纠缠于毫无价值的废话注释，程序员应该意识到，他的挫败感可以由改进代码结构而消除。
用整理代码的决心替代创造废话的冲动吧。你会发现自己成为更优秀、更快乐的程序员。
3.4.6、可怕的废话
3.4.7、能用函数或变量时就别用注释
3.4.8、归属与署名
/* Added by Ricl */
源代码控制系统非常善于记住是谁在何时添加了什么。没必要用那些小小的签名搞脏代码。
3.4.9、注释掉的代码
直接把代码注释掉是讨厌的做法。其他人不敢删除注释掉的代码。他们会想，代码依然放在那儿，一定有其原因，而且这段代码很重要，不能删除。注释掉的代码堆积在一起，将像破酒瓶的渣滓一般。
3.4.10、非本地信息
加入你一定要写注释，请确保它描述了离他最近的代码。别在本地注释的上下文环境中给出系统级的信息。
3.4.11、信息过多
别再注释中添加有趣的历史性话题或者无关的细节描述。
3.4.12、不明显的关系
注释及其描述的代码之间的联系应该显而易见。如果你不嫌弃麻烦要写注释，至少让读者能看着注释和代码，并且理解注释所谈何物。
3.4.13、函数头
短函数不需要太多描述。为只做一件事的短函数选个好名字，通常要比写函数头注释要好。
扫一扫
被折叠的 条评论
为什么被折叠?
到【灌水乐园】发言
