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

總結

以上是生活随笔為你收集整理的在下一个项目中不使用JavaDoc的5大原因的全部內容，希望文章能夠幫你解決所遇到的問題。

如果覺得生活随笔網站內容還不錯，歡迎將生活随笔推薦給好友。