Java 开发中常见的危险信号（中）

Dustin Marx 是一位专业软件开发者，从业已经有 17 年的时间，他拥有电子工程学士学位，还是一位 MBA。Dustin 维护着一个博客，专门介绍软件开发的各个主题。近日，他撰文谈到了Java 开发中常见的危险信号，提出了在日常的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 注释）应该尽量少一些，而且主要应该关注于“为什么”这么写而不是“如何做”。代码自身应该能够说明“如何”这一问题，不过很多时候是无法清楚地解释出“为什么”（由于客户/ 管理方向、设计决策、正式的接口需求、正式的算法需求等等）。

实现继承（extends）

我看到很多时候使用extends（实现继承）都很不错，也适合于相应的场景。但很多时候也存在使用不当的情况，实现继承会导致更多的麻烦。 Allen Holub 曾说到 extends 是邪恶的，四人帮的设计模式一书也用了很大的篇幅解释为何说组合要比实现继承更好。随着编写Java 代码时间的不断增长，更为重要的是随着我维护Java 代码时间的不断增长，我越来越觉得组合相对于实现继承的优势了。我确实看到了实现继承所带来的好处，不过更多的时候类是被“硬塞”到继承体系当中的，子类只不过是对 UnsupportedOperationExceptions 打洞或是“空实现”，因为他们所继承下来的方法并不适用于他们自己。加上 Effective Java 一书中所提及的继承问题（比如说具体类的 equals 与 hashCode 方法实现等），这真就成了一个大问题了。实现继承并不总是糟糕的，不过很多人经常没有正确地使用他们，因此我觉得这是个“危险信号”。

无作用的代码

程序中出现用不上的代码永远都不是一件好事。人们很快就会忘记它是怎么用的，为什么要这么用。不久之后，开发者就想知道这是不是出于某个原因被扔在那里的。无作用的代码不仅会无意义地增加代码长度，增加维护的复杂度，对于 IDE 来说，无作用的代码还有可能会被不小心调用，这种情况说明代码基出现了问题。

注释掉的代码

注释掉的代码可能不像可执行的、无意义的代码那么糟糕，因为至少它不会被不小心地调用，显然，这些代码是不会被用到的，不过这仍旧是个危险信号，因为它表明可能会出现潜在的代码基问题。就像无意义的可执行代码一样，注释掉的代码越多，人们就越难理解代码为何会出现在那里、为什么会被注释掉、不使用了为什么不将其删除掉。开发者不敢删除他们，因为留下来肯定是有原因的，只不过没人能够记起来原因是什么了。

To-Do 语句

现在越来越流行向代码添加“to-do”语句了，因为现代的 Java IDE 会为其提供特别的支持与特性。这些特性很有帮助，因为他们经常会将 todo 标记放在审查列表中，不过“to-do”注释依然是个危险信号，可能会带来与无意义的代码和注释掉的代码相同的问题。当然了，我也会使用“to-do”语句实现短期提醒，不过我觉得最好为其加上一个“过期日期”和联系信息，这样人们就可以清理他们了。加上过期日期与联系信息后，代码中的“to-do”注释就不会一直存在了，否则没有人会记得他们是干什么的，也没人敢删除他们，因为他们可能是在某个时间点被加进去的，很可能是经过某人的深思熟虑后才添加的。当我看到代码中的“to do”语句时，我真是没有任何的办法，只是想知道代码是不是缺少某些功能。