Java 理論和實踐：我必須對那些內容進行文檔編制嗎？

2019-11-18 14:41:51

字體：大中小

來源：轉載

供稿：網友

　　java 語言按照 Javadoc 注釋約定采用了一種集成的方法來進行 API 文檔編制。Javadoc 工具可以幫助生成好的 API 文檔，然而大多數 Java API 文檔卻很糟糕。因為它是源代碼的一部分，所以 API 的文檔編制職責最終還是落到了工程師身上。在本文中，Brian 對 Java 文檔編制實踐的當前狀態進行了嚴厲的批評，同時提供了一些關于如何編寫更有用的 Javadoc 的準則。
對于大多數 Java 類庫來說，Javadoc 是唯一的文檔。而且，除了商業軟件組件之外，許多 Java 類不會用到 Javadoc。雖然 Javadoc 作為 API 參考工具很出色，但對于了解類庫是如何組織的和應該如何使用它來說，它卻是一種十分差勁的方法。并且即便用了 Javadoc，它通常只包含有關方法完成了什么的最基本信息，而忽略了諸如錯誤處理、參數及返回值的作用域和范圍、線程安全、鎖定行為、前置條件、后置條件、不變條件或副作用之類的重要特性。

向 Javadoc 學習
對于包括大多數開放源碼包和大多數內部開發的組件在內的許多 Java 工具而言，實際情況是：包括 Javadoc 在內，幾乎所有類庫或組件都不具有有效的文檔。這就意味著開發人員要從 Javadoc 學習使用工具，而且我們應該考慮根據這一現實組織我們的 Javadoc。我經常開玩笑說：現在，Java 程序員需要具備的最重要的技能之一是熟練地使用 Google 和 Javadoc 來對那些文檔編制得十分糟糕的 API 進行“逆向工程”。這可能是真的，但卻并不十分好笑。

大多數 Java 包都有某種“根”對象，它是在得到該工具內的任何其它對象之前，必須創建的第一個對象。在 JNDI 中，該根對象是 Context，而在 JMS 和 JDBC 中，它是 Connection。假如有人告訴您 JDBC 中的基礎對象是 Connection，以及如何獲得這一對象，那么接著您很可能會從 Javadoc 中通過仔細察看 Javadoc 中可用的方法列表找到如何創建并執行 Statement，以及如何迭代生成的 ResultSet。但您如何知道獲得 Connection 是您的第一步呢？Javadoc 在包內按照字母順序組織類，在類中按照字母順序組織方法。遺憾的是，Javadoc 中沒有神奇的“從這里開始（Start Here）”記號把讀者帶到瀏覽 API 的邏輯開始位置。

包描述
最接近“從這里開始”記號的是包描述，但它卻很少得到有效的使用。假如將文件 package.Html 與源代碼一起放在一個包中，那么標準的 doclet 會將已生成的 package-summary.HTML 文件中的內容連同類列表一起放在該包內。遺憾的是，生成我們都很熟悉的 HTML 文檔的標準 doclet 卻無法使包描述易于找到。假如您單擊左上窗格中的某個包，那么這會在左下窗格中產生方法列表，但并不會在主窗格中產生包的摘要 — 必須單擊左下窗格中的包名稱來查看摘要。但不要緊，究竟大多數包并沒有包描述。

包文檔是一個放置“從這里開始”文檔的極好的地方，這一文檔用來概述包做什么、主要摘要是什么以及從何處開始瀏覽包的 Javadoc。

類文檔
除包文檔之外，特定于類的文檔對于幫助用戶徹底了解新工具也能起到重要的作用。類文檔當然應該包括此特定類做什么的描述，但還應該描述該類與包中的其它類如何關聯，非凡是要標識任何與該類相關的工廠類。例如，JDBC 中的 Statement 類文檔應該說明：Statement 是通過 Connection 類的 createStatement() 方法獲得的。這樣，假如一個新用戶偶然進入 Statement 頁面，那么他會發現首先他需要獲得 Connection。對每個類都應用這一約定的包會迅速為用戶指出根對象，用戶因而能夠得心應手。

因為 Javadoc 是圍繞對特定類進行文檔編制而設計的，因此在 Javadoc 中通常沒有明顯的位置來放置演示幾個相關類一起使用的示例代碼。但由于一味地側重于特定類或方法的文檔編制，我們失去了討論如何組合包中內容的機會。假如對于根對象，在包文檔或類文檔中有一個演示一些基本用法的簡單代碼示例，則對于許多用戶來說，將是非常有用的。例如，Connection 類文檔可以有一個簡單示例，該示例獲取連接、創建預編譯語句、執行該語句并迭代結果集。從技術上說，這可能不屬于 Connection 頁面，因為它還描述了包中的其它類。然而，尤其是當結合了上面那種引用當前類所依靠的類的技術時，用戶才能非常迅速地找到獲取簡單的實用示例的途徑，不管類的組織方式如何。

糟糕的文檔 == 糟糕的代碼
對于大多數 Java 類庫來說，除了那些作為打包組件出售的商業產品之外，要么沒有 Javadoc，要么非常糟糕。由于存在的事實是對于大多數包來說，Javadoc 是我們擁有的唯一文檔，這基本上意味著使我們自己陷入了這樣的困境：除了作者之外，其他人沒法使用我們的大部分代碼 — 假如不付出重大的“考古”一樣的努力，至少會這樣。

由于文檔現在是代碼的一部分，因此我認為是軟件工程社區形成一個共識的時候了，這就是，即使代碼很出色，假如文檔很糟糕，也應該被認為是差勁的代碼，因為不能有效地重用。單元測試不久前還聲譽不佳，只是到了最近它才受到了許多工程師的青睞，就和它一樣，為了改善我們生產的軟件的可靠性和可重用性，API 文檔也必須成為開發過程的一個集成部分。

上一篇：Java 理論與實踐：變還是不變？

下一篇：Java 理論與實踐: Web 層的狀態復制