Java进阶之路【代码篇】——《CleanCode》编程规则精编（3）注释

来自CleanCode原书中的一句话，告诉了我们注释的核心原则。

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

注释不能美化糟糕的代码，能用代码说明的问题，就不要用注释来说明。
《CleanCode》这本书作为Java的必读书目之一，关于注释的这个观点却还是有许多人都不明白。

甚至某些公司对于注释有着某些变态的格式要求，我真的是只能抱之以呵呵。

如果看函数名就能明白函数的功能的话，那你再把函数名解释成中文写出来的意义何在？

什么是好的注释

• 对意图的解释
  对函数名无法表达出来含义的补充

• 阐释
  用来解释用代码难以表达的 参数或返回值的意义

• 警示

• TODO与FIXME
  这里要注意的问题是，TODO的作用是提醒自己此处的代码有尚未完成的内容，或者需要解决的问题。而不是写出一段糟糕的代码，写一个TODO留给其他人来处理。

• 公共API中的Javadoc
  注意公共二字，编写诸如类库等代码时，编写良好且完整的Javadoc是很有意义的。原书作者认为非公共类库代码的Javadoc几乎是没有任何必要的，对此观点我是持保留态度的。毕竟在IDE开发中，Javadoc带来的便利还是显而易见的。不过那些@author @since甚至放个什么mailto的链接之类的，除了装个“我会写html”的逼，貌似真的并没有什么实际用途。

坏注释

废话

• 喃喃自语

  如果只是因为你觉得应该或者因为过程需要就添加注释，那就是无谓之举

• 多余的注释
  如果代码描述的已经足够清楚，就没有必要再添加一些重复代码意义的注释。至少，不要再给标准JavaBean里的set/get方法写注释了，好么？很蠢的啊，朋友。

• 位置标记

• 归属与命名
  没有必要再代码上加上这是谁添加的，版本控制系统会记录这些信息。

• 注释掉的代码
  谁也不知道注释掉的代码究竟有没有实际意义，不敢轻易删除。久而久之就导致源代码中充斥着大量被注释掉的代码，实际这些代码中可能包含着相当多的错误，对于当前版本来说已经毫无意义。
  勇敢的删掉他们吧，看见一条删一条。版本管理工具会保存这些愚蠢的东西的。

• 函数头

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

• 信息过多
  别去写个注释评论某段代码写的怎么样。要不你就重构它，要么你就别再在糟糕的代码上添乱了。

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

愚蠢的规则

什么是愚蠢的规则呢？就是明明它很蠢，却会被要求那样去做。

• 循规式注释

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

• 日志式注释
  在目前完善的源代码版本控制系统管理下，日志式注释毫无意义

• 不明显的联系
  不要让注释本身还需要解释

  注释的作用是解释未能自行解释的代码

错误和误导类

• 误导性注释
  错误的注释，不如没有。

• 可怕的废话
  本身是废话，而且注释内容还包含错误的引导信息

• 非本地信息

  假如你一定要写注释，请确保它描述了离它最近的代码

个人取舍

CleanCode中还提出了几种坏注释的情况，但我个人认为还有待商榷，大家可以根据自己的情况自行选择是否要写这类注释。

• 括号后面的注释
  个人认为在比较长的函数里，这种注释还是有意义的。例如JS中的Ajax调用。
  作者之所以认为这种类型的注释属于 坏注释，主要原因在于，通常出现这种注释是因为函数写的太长了。理应重构这个函数，让他变得符合 函数 的编码规范，而不是用注释来解决这个问题。

• HTML注释
  作者认为HTML注释将影响注释的可读性。在这里我还是比较支持作者在之后列出的观点，即：在向外发布的公共API中正确使用良好的Javadoc注释，在不对外发布的源码中不使用Javadoc注释，以提高源码的可读性。

• 能用函数或变量时就别用注释
  这一点还是有待商榷，在《重构》一书中作者列出的“代码坏味道”中其中一项便是过多的临时变量。
  该如何取舍，就得结合具体情况加以分析了

小结

不要在注释里写废话，不要因为某些规定去写废话。
保证注释中的内容是正确的，代码修改时注意同时修改相应的注释。
把注释放在它注释内容的合适的位置。
在写一段注释之前，先思考下，能否通过重构代码的方式来避免写这一段注释？

另：
如果项目组里的人英语水平不是很好，合理的英文解释类注释还是有一定意义的。因为，成员的计算机英语，某些时候只有自己能理解……