?
快捷搜索:  as  test  1111  test aNd 8=8  test++aNd+8=8  as++aNd+8=8  as aNd 8=8

澳門威尼人斯app平臺:Javadoc 利弊分析

?

我必須對那些內容進行文檔體例嗎?

采納 Javadoc 形式的集成文檔有利有弊

級別:中級

Brian Goetz([email protected]

首席顧問,Quiotix Corp

2002 年 10 月

Java 說話按照 Javadoc 注釋約定采納了一種集成的措施來進行 API 文檔體例。Javadoc 對象可以贊助天生好的 API 文檔,然而大年夜多半 Java API 文檔卻很糟糕。由于它是源代碼的一部分,以是 API 的文檔體例職責終極照樣落到了工程師身上。在本文中,Brian 對 Java 文檔體例實踐確當前狀態進行了嚴峻的品評,同時供給了一些關于若何編寫更有用的 Javadoc 的準則。

對付大年夜多半 Java 類庫來說,Javadoc 是獨一的文檔。而且,除了商業軟件組件之外,許多 Java 類不會用到 Javadoc。雖然 Javadoc 作為 API 參考對象很出色,但對付懂得類庫是若何組織的和應該若何應用它來說,它卻是一種十分差勁的措施。并且即便用了 Javadoc,它平日只包孕有關措施完成了什么的最基礎信息,而輕忽了諸如差錯處置懲罰、參數及返回值的感化域和范圍、線程安然、鎖定行徑、前置前提、后置前提、不變前提或副感化之類的緊張特點。

向 Javadoc 進修

對付包括大年夜多半開放源碼包和大年夜多半內部開拓的組件澳門威尼人斯app平臺在內的許多 Java 對象而言,實際環境是:包括 Javadoc 在內,險些所有類庫或組件都不具有有效的文檔。這就意味著開拓職員要從 Javadoc 進修應用對象,而且我們應該斟酌根據這一現實組織我們的 Javadoc。我常常開玩笑說:現在,Java 法度榜樣員必要具備的最緊張的技能之一是純熟地應用 Google 和 Javadoc 來對那些文檔體例得十分糟糕的 API 進行“逆向工程”。這可能是真的,但卻并不十分可笑。

大年夜多半 Java 包都有某種“根”工具,它是在獲得該對象內的任何其它工具之前,必須創建的第一個工具。在 JNDI 中,該根工具是 Context,而在 JMS 和 JDBC澳門威尼人斯app平臺 中,它是 Connection。假如有人奉告您 JDBC 中的根基工具是 Connection,以及若何得到這一工具,那么接著您很可能會從 Javadoc 中經由過程仔細不雅察 Javadoc 中可用的措施列表找到若何創建并履行 Statement,以及若何迭代天生的 ResultSet。但您若何知道得到 Connection 是您的第一步呢?Javadoc 在包內按照字母順序組織類,在類中按照字母順序組織措施。遺憾的是,Javadoc 中沒有神奇的“從這里開始(Start Here)”暗號把讀者帶到瀏覽 API 的邏輯開始位置。

包描述

最靠近“從這里開始”暗號的是包描述,但它卻很少獲得有效的應用。假如將文件 package.html 與源代碼一路放在一個包中,那么標準的 doclet 會將已天生的 package-summary.html 文件中的內容連同類列表一路放在該包內。遺憾的是,天生我們都很認識的 HTML 文檔的標準 doclet 卻無法使包描述易于找到。假如您單擊左上窗格中的某個包,那么這會在左下窗格中孕育發生措施列表,但并不會在主窗格中孕育發生包的擇要 — 必須單擊左下窗格中的包名稱來查看擇要。但沒緊要,終究大年夜多半包并沒有包描述。

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

類文檔

除包文檔之外,特定澳門威尼人斯app平臺于類的文檔對付贊助用戶徹底懂得新對象也能起到緊張的感化。類文檔當然應該包括此特定類做什么的描述,但還應該描述該類與包中的其它類若何關聯,分外是要標識任何與該類相關的工廠類。例如,JDBC 中的 Statement 類文檔應該闡明:Statement 是經由過程 Connection 類的 createStatement() 措施得到的。這樣,假如一個新用戶偶爾進入 Statement 頁面,那么他會發明首先他必要得到 Connection。對每個類都利用這一約定的包會迅速為用戶指出根工具,用戶因而能夠輕車熟路。

由于 Javadoc 是環抱對特定類進行文檔體例而設計的,是以在 Javadoc 中平日沒有顯著的位置來放置演示幾個相關類一路應用的示例代碼。但因為一味地偏重于特定類或措施的文檔體例,我們掉去了評論爭論若何組合包中內容的時機。假如對付根工具,在包文檔或類文檔中有一個演示一些基礎用法的簡單代碼示例,則對付許多用戶來說,將是異常有用的。例如,Connection 類文檔可以有一個簡單示例,該示例獲取連接、創建預編譯語句、履行該語句并迭代結果集。從技巧上說,這可能不屬于 Connection 頁面,由于它還描述了包中的其它類。然而,尤其是當結合了上面那種引用當前類所依附的類的技巧時,用戶才能異常迅速地找到獲取簡單的實用示例的道路,不管類的組織要領若何。

糟糕的文檔 == 糟糕的代碼

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

因為文檔現在是代碼的一部分,是以我覺得是軟件工程社區形成一個共識的時刻了,這便是,縱然代碼很出色,假如文檔很糟糕,也應該被覺得是差勁的代碼,由于不能有效地重用。單元測試不久前還聲望不佳,只是到了近來它才受到了許多工程師的青睞,就和它一樣,為了改良我們臨盆的軟件的靠得住性和可重用性,API 文檔也必須成為開拓歷程的一個集成部分。

編寫 Javadoc 便是某種形式的代碼反省

編寫合理的 Javadoc 也會孕育發生副感化,它迫使我們進行某種形式的代碼反省,來鉆研類的體系布局和它們之間的關系。假如單個包、類或措施很難體例文檔,那么或許可以考試測驗同時對多個包、類或措施進行文檔體例,這應該是個提示,即可能它必要從新設計。

文檔的自我反省方面使得某些方面加倍緊張,即在開拓歷程中盡早編寫 Javadoc,然后跟著代碼的賡續開拓,按期對其進行反省,而不是僅僅等待代碼完成再編寫文檔(假如有殘剩光陰的話)。后一種策略十分常見,它將編寫文檔拖到項目著末,而那韶光陰安排十分首要,開拓職員澳門威尼人斯app平臺的壓力也很大年夜。結果再常見不過了,便是圖 1 所示的那種一文不值的文檔,它只供給了“文檔假象”。用戶真正必要的是懂得該類的事情道理,而該文檔卻沒有供給任何這樣的信息。

清單 1. 范例的一文不值的 Javadoc

/**

* Represents a command history

*/

public class CommandHistory {

/**

* Get the command history for a given user

*/

public static CommandHistory getCommandHistory(String user) {

. . .

}

}

那么好的文檔包括哪些內容呢?

上面描述的組織技巧(在類描述中引用相關類或工廠類,也包括了包概述和代碼樣本)是形成優秀文檔的好起頭。它有助于新用戶應用 Javadoc 懂得新對象。

但體系布局的概述只完成了義務的一半。另一半則是具體地解釋措施做什么和不做什么、在什么前提下運行以及它們若何處置懲罰差錯前提。大年夜多半 Javadoc 都沒有完全供給所需的信息,即就是那些充分描述了措施在期望環境下的行徑的 Javadoc 也是如斯,這些缺少的信息包括:

措施若何處置懲罰差錯前提或分歧要求的輸入

若何將差錯前提傳回給調用者

可能會拋出哪個特定非常的子類

哪些值對付輸入是有效的

類不變前提、措施前置前提或措施后置前提

副感化

在措施之間是否有緊張聯接

類若何處置懲罰多個線程同時造訪一個實例的環境。

Javadoc 約定供給了 @param 標記,它讓我們除了能夠對參數的名稱和類型體例文檔之外,還可以對其意義體例文檔。然而,澳門威尼人斯app平臺并不是所有的措施都能很好地吸收參數的任何值。例如,雖然可以合法地向任何獲取工具參數的措施通報空值(null)而不違反類型反省規則,但并不是所有的措施都能在傳入空值時正常事情。Javadoc 應該顯式地描述有效的參數范圍,假如它盼望某個參數非 null,那么它應該這樣描述,而假如它期望參數值在某個范圍內,例如某種長度的字符串或大年夜于 0 的整數,那么它也應該那樣描述。并非所有措施都仔細反省其參數的有效性;不進行有效性反省也沒有體例關于可吸收的輸入范圍的文檔,這二者的結合為劫難埋下了隱患。

返回代碼

Javadoc 使得描述返回值的意義變得很輕易,但正如措施參數一樣,@return 標記應該包括對可能返回的值范圍的具體描述。對付工具取值的返回類型而言,它會返回空值嗎?對付整數取值的返回類型而言,結果會限定在一個已知值或非負值的聚攏上嗎?任何返回代碼都有特殊意義嗎,例如從 java.io.InputStream.read() 返回 -1 表示文件停止符?返回代碼會被用來表示例如假如無法找到表項則返回空值那樣的差錯前提嗎?

非常

標準 doclet 復制措施的 throws 子句,但 Javadoc @throws 標記應該更為詳細。例如,NoSuchFileException 是 IOException 的子類,但 java.io 中的大年夜多半措施卻只被聲明為拋出 IOException。然而,措施可能自力于其它 IOException 而拋出 NoSuchFileException,這是調用者要懂得的很有用的事實 — 它應該被包括在 Javadoc 中。還應該指出拋出各類非常類的實際差錯前提,以便調用者知道在給定非常被拋出時該采取什么矯正步伐。應該用 @throws 標記對措施可能拋出的每個經反省的或未經反省的非常體例文檔,并對激發拋出非常的前提體例文檔。

前置前提、后置前提和不變前提

免責聲明:以上內容源自網絡,版權歸原作者所有,如有侵犯您的原創版權請告知,我們將盡快刪除相關內容。

您可能還會對下面的文章感興趣:

快三平台开户