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
...)
)
)
