javadoc 開源項目

JavaDoc對于框架和庫的開發(fā)是絕對必需的，這些框架和庫為其他框架（例如Spring Framework，JDK）提供了公共接口。 對于內(nèi)部企業(yè)軟件和/或產(chǎn)品開發(fā)，我有以下原因會在將來忽略“ 100％JavaDoc Policy”。

1）大約95％的評論沒有附加值的觀察

如果您有一個JavaDoc在項目中是強制性的規(guī)則，則大多數(shù)開發(fā)人員將使用JavaDoc生成向?qū)?#xff08;例如http://jautodoc.sourceforge.net/ ）。 這些生成的評論很快，并且創(chuàng)建了幾乎一文不值的內(nèi)容。 但是對于像PMD這樣的靜態(tài)代碼分析工具，一切看起來都不錯。

現(xiàn)有的大多數(shù)JavaDoc描述都解釋了WHAT，而不是WHY。 每個開發(fā)人員都應(yīng)該能夠閱讀源代碼，而事實就是代碼。 通常，僅需要注釋即可了解開發(fā)人員為何決定使用當(dāng)前解決方案。 在某些情況下，對引用的基本概念的提示可能會有所幫助，例如設(shè)計模式，教科書章節(jié)，標準算法。

2）使用斷言來檢查有效參數(shù)比純文本描述更有效

即使使用100％JavaDoc和高質(zhì)量的描述，只要沒有明顯的問題出現(xiàn)，許多開發(fā)人員就不會閱讀注釋。 對于這些情況，對具有斷言和/或驗證功能的方法的有效輸入進行自動檢查會有所幫助。 Spring框架是使用Asserts的一個很好的例子。 開發(fā)或測試過程中的異常比不讀注釋有更多幫助。

3）源代碼的可讀性越來越差

廣泛的JavaDoc可能不是最關(guān)鍵的缺點是可讀性差。 屏幕空間有限。 這也可能是錯誤的根源，因為我們是人類，屏幕上顯示的更多代碼意味著更好的概覽。

4）隨著時間的流逝，很多評論都錯了

假設(shè)您有完善的JavaDoc注釋，并且有一些增強請求，缺陷或重構(gòu)。 許多評論將是不正確的，因為沒有人花時間來更新它們。 這是一個非常糟糕的情況。 開發(fā)人員應(yīng)該在評論或新實現(xiàn)中相信測試什么？ 沒有文件比不一致或過時的文件更好。

5）重構(gòu)將更慢

在大多數(shù)情況下，借助現(xiàn)代開發(fā)工具支持，重構(gòu)是一項快速而輕松的工作。 更新JavaDoc仍然是一個手動過程，需要很多時間。 這導(dǎo)致由于JavaDoc導(dǎo)致不需要重構(gòu)的情況。
建議不只是背面和白色。 在某些情況下，JavaDoc非常有意義，并為維護團隊創(chuàng)造了價值。 在團隊中討論何時使用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 開源項目

總結(jié)

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

如果覺得生活随笔網(wǎng)站內(nèi)容還不錯，歡迎將生活随笔推薦給好友。