本文来源于我在InfoQ中文站原创的文章，原文地址是：http://www.infoq.com/cn/news/2013/12/common-red-flags-in-java-1

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”语句时，我真是没有任何的办法，只是想知道代码是不是缺少某些功能。