1）大约95％的评论没有附加值的观察
如果您有一个JavaDoc在项目中是强制性的规则，则大多数开发人员将使用JavaDoc生成向导。 这些生成的评论很快，并且创建了几乎一文不值的内容。 但是对于像PMD这样的静态代码分析工具，一切看起来都不错。
现有的大多数JavaDoc描述都解释了WHAT，而不是WHY。 每个开发人员都应该能够阅读源代码，而事实就是代码。 通常，仅需要注释即可了解开发人员为何决定使用当前解决方案。 在某些情况下，对引用的基本概念的提示可能会有所帮助，例如设计模式，教科书章节，标准算法。
2）使用断言来检查有效参数比纯文本描述更有效
即使使用100％JavaDoc和高质量的描述，只要没有明显的问题出现，许多开发人员就不会阅读注释。 对于这些情况，对具有断言和/或验证功能的方法的有效输入进行自动检查会有所帮助。 Spring框架是使用Asserts的一个很好的例子。 在开发或测试期间的异常比不读注释有更多帮助。
3）源代码的可读性越来越差
广泛的JavaDoc可能不是最关键的缺点是可读性差。 屏幕空间有限。 这也可能是错误的根源，因为我们是人类，屏幕上显示的更多代码意味着更好的概览。
4）随着时间的流逝，很多评论都错了
假设您有完善的JavaDoc注释，并且有一些增强请求，缺陷或重构。 许多评论将是不正确的，因为没有人花时间来更新它们。 这是一个非常糟糕的情况。 开发人员应该在评论或新实现中相信测试吗？ 没有文件比不一致或过时的文件更好。
5）重构将更慢
在大多数情况下，借助现代开发工具支持，重构是一项快速而轻松的工作。 更新JavaDoc仍然是一个手动过程，需要很多时间。 这导致由于JavaDoc导致不需要重构的情况。
建议不只是背面和白色。 在某些情况下，JavaDoc非常有意义，并为维护团队创造了价值。 在团队中讨论何时使用JavaDoc。 我保证将来会这样做。
