Effective Java 第三版——74. 文檔化每一個方法拋出的全部異常

Tips
書中的源代碼地址：https://github.com/jbloch/effective-java-3e-source-code
注意，書中的有些代碼裏方法是基於Java 9 API中的，因此JDK 最好下載 JDK 9以上的版本。

74. 文檔化每一個方法拋出的全部異常

描述方法拋出的異常，是正確使用方法所需文檔的重要部分。所以，花時間爲每一個方法拋出的全部異常創建文檔是很是重要的(條目 56)。

始終單獨聲明檢查異常，並使用Javadoc @throw標籤，精確地記錄每次拋出異常的條件。不要使用「快捷方式」聲明一個方法拋出它能夠拋出的多個異常類的超類。做爲一個極端的例子，不要聲明公共方法拋出Exception類，或者更糟，拋出Throwable類。除了拒絕向方法的用戶提供關於它可以拋出的異常的任何指導以外，這樣的聲明還極大地阻礙了方法的使用，由於它極大掩蓋了可能在相同上下文中拋出的任何其餘異常。這個建議的一個例外狀況是main方法，它能夠安全地聲明爲拋出Exception類，由於它只被虛擬機調用。

雖然Java語言不要求程序員聲明方法可以拋出的未檢查異常（unchecked exceptions），但明智的作法是像檢查異常同樣仔細地在文檔中記錄它們。未檢查異常一般表示編程錯誤(條目 70)，讓程序員熟悉他們可能犯的全部錯誤能夠幫助他們避免犯這些錯誤。方法能夠拋出的未檢查異常的良好文檔列表有效地描述了成功執行的先決條件。每一個公共方法的文檔都必須描述它的先決條件(條目 56)，記錄它的未檢查異常是知足這個需求的最佳方法。

特別重要的是，接口中的方法要在文檔中記錄它們可能拋出的未檢查異常。此文檔構成接口通用約定的一部分，並支持接口的多個實現之間的公共行爲。

使用Javadoc @throw標籤記錄方法能夠拋出的每一個異常，可是不要對未檢查的異常使用throws關鍵字。重要的是，使用你的API的程序員必須知道哪些方法是檢查異常，哪些是未檢查異常，由於程序員的責任在這兩種狀況下有所不一樣。Javadoc @throws標籤生成的文檔在方法聲明中沒有對應的拋出子句，這向程序員提供了一個強烈的視覺暗示，說明該異常是未檢查異常。

應該注意的是，在文檔中記錄每一個方法能夠拋出的全部未檢查異常是理想的，在現實世界中並不老是能夠實現。當類進行修訂時，若是將導出的方法修改成拋出額外的未檢查異常，這並不違反源代碼或二進制兼容性。假設一個類從另一個獨立編寫的類調用一個方法。第一個類的做者可能會仔細記錄全部的每一個方法拋出未經檢查的異常，可是若是第二個類的做者修改成額外的未經檢查的異常，極可能第一個類(未經修訂)將傳播新的未經檢查異常，儘管沒有文檔記錄它們。

若是一個類中的許多方法出於相同的緣由引起異常，能夠在類的文檔註釋中記錄異常，而不是爲每一個方法單獨記錄異常。一個常見的例子是NullPointerException。類的文檔註釋能夠這樣說：「若是在任何參數中傳遞了null對象引用，該類中的全部方法都會拋出NullPointerException」，或者相似的描述。

總之，在文檔中記錄你所編寫的每一個方法可能引起的每一個異常。對於未檢查異常、檢查異常以及抽象方法和具體實現方法中都是如此。這個文檔應該在文檔註釋中採用@throws標籤的形式。在方法的throws子句中分別聲明每一個檢查異常，但不要聲明未檢查異常。若是未記錄方法可能拋出的異常，其餘人將很難或不可能有效地使用你的類和接口。