??描述方法拋出的異常是正確使用方法所需文檔的重要部分狐树。因此，花時間仔細記錄每個方法拋出的所有異常是非常重要的(item56)。
??始終單獨聲明已檢查異常替梨，并使用Javadoc @throw標記精確地記錄每次拋出異常的條件撬腾。不要使用快捷方式聲明一個方法拋出它可以拋出的多個異常類的超類螟蝙。作為一個極端的例子，不要聲明公共方法拋出Exception时鸵，或者更糟胶逢，拋出Throwable厅瞎。除了拒絕向方法的用戶提供關(guān)于它能夠拋出的異常的任何指導之外，這樣的聲明還極大地阻礙了方法的使用初坠，因為它有效地掩蓋了可能在相同上下文中拋出的任何其他異常和簸。這個建議的一個異常是main方法，它可以安全地聲明為拋出異常碟刺，因為它只被VM調(diào)用锁保。
??雖然該語言不要求程序員聲明方法能夠拋出的未檢查異常，但明智的做法是像檢查異常一樣仔細地記錄它們半沽。未檢查異常通常表示編程錯誤( item70 )爽柒，讓程序員熟悉他們可能犯的所有錯誤可以幫助他們避免犯這些錯誤。方法可以拋出的未檢查異常的良好文檔列表有效地描述了成功執(zhí)行的先決條件者填。每個公共方法的文檔都必須描述它的先決條件(item56)浩村，記錄它的未檢查異常是滿足這個需求的最佳方法。
??特別重要的是占哟，接口中的方法要記錄它們可能拋出的未檢查異常心墅。此文檔構(gòu)成接口通用契約的一部分，并支持接口的多個實現(xiàn)之間的公共行為榨乎。
??使用Javadoc @throw標記記錄方法可以拋出的每個異常怎燥，但是不要對未檢查的異常使用throw關(guān)鍵字。重要的是蜜暑，使用您的API的程序員知道哪些異常被檢查铐姚，哪些異常被檢查，因為程序員的職責在這兩種情況下是不同的肛捍。Javadoc @throw標記生成的文檔在方法聲明中沒有對應的throw子句隐绵，這向程序員提供了一個強烈的視覺提示，說明異常是未檢查的篇梭。
??應該注意的是氢橙，記錄每個方法可以拋出的所有未檢查異常是理想的，在現(xiàn)實世界中并不總是可以實現(xiàn)恬偷。類進行修訂時悍手，如果將導出的方法修改為拋出額外的未檢查異常，這并不違反源或二進制兼容性袍患。假設(shè)一個類從另一個獨立編寫的類調(diào)用一個方法坦康。前類的作者可能會仔細記錄所有的每個方法拋出未經(jīng)檢查的異常,如果后者類修改把額外的未經(jīng)檢查的異常,很可能前類(未經(jīng)修訂)將傳播新的未經(jīng)檢查的異常,盡管它沒有文檔。
??如果類中的許多方法出于相同的原因引發(fā)異常诡延，可以在類的文檔注釋中記錄異常而不是為每個方法單獨編寫文檔滞欠。一個常見的例子是NullPointerException。一個類的文檔注釋可以這樣說肆良，
“如果在任何參數(shù)中傳遞null對象引用筛璧，該類中的所有方法都會拋出NullPointerException逸绎，”或類似的語句。
??總之夭谤，記錄您所編寫的每個方法可能引發(fā)的每個異常棺牧。對于未檢查異常和已檢查異常以及抽象方法和具體方法都是如此。本文檔應采用以下形式@在doc注釋中拋出標記朗儒。在方法的throw子句中分別聲明每個已檢查的異常颊乘，但不要聲明未檢查的異常。如果您不能記錄方法可能拋出的異常醉锄，其他人將很難或不可能有效地使用您的類和接口乏悄。
本文寫于2019.7.22，歷時1天
