ITEM 74: DOCUMENT ALL EXCEPTIONS THROWN BY EACH METHOD
??對(duì)方法拋出的異常的描述是該方法文檔的重要部分梯刚。因此，花時(shí)間仔細(xì)記錄每個(gè)方法拋出的所有異常是非常重要的(item 56)笋敞。
??我們應(yīng)當(dāng)聲明已檢查的異常捣作，并使用 Javadoc @throws標(biāo)記精確記錄拋出每個(gè)異常的條件吼驶。不要采取這樣的捷徑：聲明一個(gè)方法拋出它可以拋出的多個(gè)異常類的某個(gè)超類董虱。作為一個(gè)極端的例子，不要聲明一個(gè)公共方法會(huì)拋出異常获讳，或者更糟的是阴颖，拋出 Throwable。除了拒絕向用戶提供任何關(guān)于方法能夠拋出異常的指導(dǎo)之外丐膝，這樣的聲明還會(huì)極大地阻礙方法的使用量愧，因?yàn)樗谏w了在同一上下文中可能拋出的任何其他異常。這個(gè)建議的一個(gè)例外是 main 方法帅矗，它可以安全地聲明為拋出 Exception偎肃，因?yàn)樗槐籚M調(diào)用。
??雖然 Java 不要求程序員聲明方法能夠拋出的未檢查異常浑此，但是明智的做法是像記錄已檢查異常一樣仔細(xì)地記錄它們累颂。未經(jīng)檢查的異常通常表示編程錯(cuò)誤(item 70)，讓程序員熟悉他們可能會(huì)犯的所有錯(cuò)誤可以幫助他們避免這些錯(cuò)誤尤勋。一個(gè)記錄良好的方法可以拋出的未檢查異常列表描述了成功執(zhí)行的先決條件喘落。每個(gè)公共方法的文檔都必須描述其先決條件(item 56)，而記錄未檢查的異常是滿足這一需求的最佳方式最冰。尤其重要的是瘦棋，接口中的方法要記錄它們可能拋出的未檢查異常。該文檔構(gòu)成了接口通用契約的一部分暖哨，并支持接口的多個(gè)實(shí)現(xiàn)之間的公共行為赌朋。
??使用 Javadoc @throws 標(biāo)記來記錄方法可能拋出的每個(gè)異常，但不要對(duì)未檢查的異常使用throws 關(guān)鍵字篇裁。使用您的API的程序員應(yīng)該知道方法可能拋出哪些檢查異常沛慢，哪些未檢查異常，這是很重要的达布，因?yàn)槌绦騿T在這兩種情況下的職責(zé)是不同的团甲。由 Javadoc @throws標(biāo)記生成的文檔在方法聲明中沒有包含相應(yīng)的 throws子句，它向程序員提供了一個(gè)強(qiáng)烈的可視化提示黍聂，即未檢查異常躺苦。
??應(yīng)該注意的是，記錄每個(gè)方法可能拋出的所有未檢查異常是一種理想的做法产还，在現(xiàn)實(shí)世界中并不總是可以實(shí)現(xiàn)的匹厘。當(dāng)類經(jīng)歷修訂時(shí)，如果修改導(dǎo)出的方法以拋出額外的未檢查異常脐区，這并不違反源代碼或二進(jìn)制兼容性愈诚。
??假設(shè)一個(gè)類從另一個(gè)獨(dú)立編寫的類調(diào)用一個(gè)方法。前類的作者可能會(huì)仔細(xì)記錄所有的每個(gè)方法拋出未經(jīng)檢查的異常，如果后者類修改時(shí)添加了新的未檢查異常炕柔，很可能前類(未經(jīng)修訂)將傳播新的未經(jīng)檢查的異常酌泰，盡管它沒有記錄這個(gè)新的異常。
??如果一個(gè)類中的許多方法出于相同的原因引發(fā)異常汗唱，您可以在類的文檔注釋中記錄異常宫莱，而不是為每個(gè)方法單獨(dú)記錄異常丈攒。一個(gè)常見的例子是NullPointerException哩罪。對(duì)于類的文檔注釋來說，“如果在任何參數(shù)中傳遞了null對(duì)象引用巡验，則該類中的所有方法都會(huì)拋出NullPointerException”际插，或者類似的文字。
??總之显设，記錄您編寫的每個(gè)方法可能拋出的每個(gè)異常框弛。對(duì)于未檢查異常和已檢查異常，對(duì)于抽象方法和具體方法都是如此捕捂。這個(gè)文檔應(yīng)該采用文檔注釋中的@throw標(biāo)記的形式瑟枫。在方法的throws子句中分別聲明每個(gè)檢查過的異常，但不要聲明未檢查過的異常指攒。如果沒有記錄方法可能拋出的異常慷妙，其他人將很難或不可能有效地使用您的類和接口。
ITEM 74: 在文檔中記錄方法拋出的所有異常
?著作權(quán)歸作者所有,轉(zhuǎn)載或內(nèi)容合作請(qǐng)聯(lián)系作者
- 文/潘曉璐 我一進(jìn)店門总珠，熙熙樓的掌柜王于貴愁眉苦臉地迎上來屏鳍，“玉大人，你說我怎么就攤上這事姚淆≡胁酰” “怎么了？”我有些...
- 文/不壞的土叔 我叫張陵腌逢，是天一觀的道長降淮。 經(jīng)常有香客問我，道長，這世上最難降的妖魔是什么佳鳖？ 我笑而不...
- 正文 為了忘掉前任霍殴，我火速辦了婚禮，結(jié)果婚禮上系吩，老公的妹妹穿的比我還像新娘来庭。我一直安慰自己，他們只是感情好穿挨，可當(dāng)我...
- 文/花漫 我一把揭開白布月弛。 她就那樣靜靜地躺著，像睡著了一般科盛。 火紅的嫁衣襯著肌膚如雪帽衙。 梳的紋絲不亂的頭發(fā)上，一...
- 文/蒼蘭香墨 我猛地睜開眼翩剪，長吁一口氣：“原來是場噩夢(mèng)啊……” “哼！你這毒婦竟也來了溯祸？” 一聲冷哼從身側(cè)響起肢专，我...
- 序言：老撾萬榮一對(duì)情侶失蹤，失蹤者是張志新（化名）和其女友劉穎焦辅，沒想到半個(gè)月后博杖，有當(dāng)?shù)厝嗽跇淞掷锇l(fā)現(xiàn)了一具尸體，經(jīng)...
- 正文 獨(dú)居荒郊野嶺守林人離奇死亡筷登，尸身上長有42處帶血的膿包…… 初始之章·張勛 以下內(nèi)容為張勛視角 年9月15日...
- 正文 我和宋清朗相戀三年剃根，在試婚紗的時(shí)候發(fā)現(xiàn)自己被綠了。 大學(xué)時(shí)的朋友給我發(fā)了我未婚夫和他白月光在一起吃飯的照片前方。...
- 正文 年R本政府宣布班巩，位于F島的核電站渣慕，受9級(jí)特大地震影響，放射性物質(zhì)發(fā)生泄漏。R本人自食惡果不足惜逊桦，卻給世界環(huán)境...
- 文/蒙蒙 一眨猎、第九天 我趴在偏房一處隱蔽的房頂上張望。 院中可真熱鬧强经，春花似錦睡陪、人聲如沸。這莊子的主人今日做“春日...
- 文/蒼蘭香墨 我抬頭看了看天上的太陽。三九已至码秉，卻和暖如春逮矛，著一層夾襖步出監(jiān)牢的瞬間，已是汗流浹背转砖。 一陣腳步聲響...
- 正文 我出身青樓，卻偏偏與公主長得像汞窗，于是被迫代替她去往敵國和親姓赤。 傳聞我的和親對(duì)象是個(gè)殘疾皇子，可洞房花燭夜當(dāng)晚...
推薦閱讀更多精彩內(nèi)容
- ??描述方法拋出的異常是正確使用方法所需文檔的重要部分仲吏。因此不铆，花時(shí)間仔細(xì)記錄每個(gè)方法拋出的所有異常是非常重要的(i...
- 描述一個(gè)方法所拋出的異常，是正確的使用這個(gè)方法時(shí)所需要文檔的重要組成部分裹唆，因此花點(diǎn)時(shí)間仔細(xì)的為每個(gè)方法拋出的異常建...
- 捕獲異常 使用 try 和 catch 關(guān)鍵字可以捕獲異常誓斥。try/catch 代碼塊放在異常可能發(fā)生的地方...
- ??當(dāng)一個(gè)方法拋出一個(gè)與它所執(zhí)行的任務(wù)沒有明顯關(guān)聯(lián)的異常時(shí)许帐，這是令人不安的劳坑。這種情況經(jīng)常發(fā)生在方法傳播由低層抽象拋...
- 黑色的海島上懸著一輪又大又圓的明月距芬，毫不嫌棄地把溫柔的月色照在這寸草不生的小島上。一個(gè)少年白衣白發(fā)循帐，悠閑自如地倚坐...
