Java开发中常见的危险信号

　　缺乏Javadoc注释

　　我倾向于将所有的契约方法(特别是public方法)都使用Javadoc注释起来。此外，我还觉得对属性添加注释是必要的，注释要描述清楚属性存储的内容是什么。我听说有人拿代码是“自文档”的作为不写Javadoc注释的借口，不过我对此却并不认同，我想对这些人说的是简单的Javadoc注释可以表达出相同的信息，而阅读代码则需要花费更长的时间。虽然有些方法的名字会很长，但有时也无法准确地描述清楚期望的输入条件与输出结果。我认为很多Java开发者(就像我一样)在使用JDK时更喜欢阅读它的Javadoc注释而不是JDK源代码。既然如此，那我们自己编写的代码为何就要反其道而行之呢?我有时也会阅读源代码，这主要是因为注释不够充分，或是行为与描述的不一致，还有可能是我有理由相信注释过期了。

　　我还喜欢查看类属性的Javadoc注释。有些人倾向于在public get/set方法前加上属性描述信息，不过我不喜欢这种方式，因为这么做就是在假设属性总是有get/set方法(我是不会做这种假设的)。

　　在方法的Javadoc注释中描述实现细节

　　虽然我认为没有Javadoc注释是个危险信号，不过错误地使用Javadoc注释同样也是个危险信号。Javadoc注释不应该说明实现细节，而应该关注于客户端对方法的期望(参数)与方法对客户端的期望(返回类型，还有可能是抛出异常等)。在真正的面向对象系统中，实现应该是可以在public接口下进行修改的，因此将接口文档中的这些实现细节放到Javadoc注释中是不恰当的做法。这是个“危险信号”，因为Javadoc中存在的实现细节会让我怀疑注释的时效性。换句话说，这种注释经常会过期，随着代码的不断演化而出现错误。

　　源代码中的注释

　　虽然接口(通常是Javadoc)中缺乏注释是一种危险信号，不过方法体和其他源代码中的注释也可能是个危险信号，会导致潜在的问题。如果需要为代码添加注释以帮助人们理解代码的行为，那就很有可能是代码的复杂性过大(“注释是恶臭代码的芳香剂”，这句话有些滑稽，不过在一定程度上却真的如此)。就像文中提到的众多“危险信号”一样，有时我也认为源代码中的注释是有意义的，可以提供很多信息，这时就没有必要删除这些注释了。然而，我认为代码中的注释(不是接口描述的Javadoc注释)应该尽量少一些，而且主要应该关注于“为什么”这么写而不是“如何做”。代码自身应该能够说明“如何”这一问题，不过很多时候是无法清楚地解释出“为什么”(由于客户/管理方向、设计决策、正式的接口需求、正式的算法需求等等)。