在下一个项目中不使用JavaDoc的5大原因

JavaDoc对于框架和库的开发是绝对必要的，这些框架和库为其他框架（例如Spring Framework，JDK）提供了公共接口。 对于内部企业软件和/或产品开发，我有以下原因会在将来忽略“ 100％JavaDoc策略”。

1）大约95％的评论没有附加值的观察

如果您有一个JavaDoc在项目中是强制性的规则，则大多数开发人员将使用JavaDoc生成向导（例如http://jautodoc.sourceforge.net/ ）。 这些生成的评论很快，并且创建了几乎一文不值的内容。 但是对于像PMD这样的静态代码分析工具，一切看起来都不错。

现有的大多数JavaDoc描述都解释了WHAT，而不是WHY。 每个开发人员都应该能够阅读源代码，而事实就是代码。 通常，仅需要注释即可了解开发人员为何决定使用当前解决方案。 在某些情况下，对引用的基本概念的提示可能会有所帮助，例如设计模式，教科书章节，标准算法。

2）使用断言来检查有效参数比纯文本描述更有效

即使使用100％JavaDoc和高质量的描述，只要没有明显的问题出现，许多开发人员就不会阅读注释。 对于这些情况，对具有断言和/或验证功能的方法的有效输入进行自动检查会有所帮助。 Spring框架是使用Asserts的一个很好的例子。 在开发或测试期间的异常比不读注释有更多帮助。

3）源代码的可读性越来越差

广泛的JavaDoc可能不是最关键的缺点是可读性差。 屏幕空间有限。 这也可能是错误的根源，因为我们是人类，屏幕上显示的更多代码意味着更好的概览。

4）随着时间的流逝，很多评论都错了

假设您有完善的JavaDoc注释，并且有一些增强请求，缺陷或重构。 许多评论将是不正确的，因为没有人花时间来更新它们。 这是一个非常糟糕的情况。 开发人员应该在评论或新实现中相信测试吗？ 没有文件比不一致或过时的文件更好。

5）重构将更慢

在大多数情况下，借助现代开发工具支持，重构是一项快速而轻松的工作。 更新JavaDoc仍然是一个手动过程，需要很多时间。 这导致由于JavaDoc导致不需要重构的情况。
建议不只是背面和白色。 在某些情况下，JavaDoc非常有意义，并为维护团队创造了价值。 在团队中讨论何时使用JavaDoc。 我保证将来会这样做。

参考：来自JCG合作伙伴 Markus Sprunck的Software Engineering Candies博客上的下一个项目中未使用JavaDoc的5大理由 。

翻译自: https://www.javacodegeeks.com/2012/06/top-5-reasons-for-not-using-javadoc-in.html