Effective Java 第三版——51. 仔細設計方法簽名

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

51. 仔細設計方法簽名

這一條目是API設計提示的大雜燴，但它們自己並足以設立一個單獨的條目。綜合起來，這些設計提示將幫助你更容易地學習和使用API，而且更不容易出錯。

仔細選擇方法名名稱。名稱應始終遵照標準命名約定(條目68)。你的主要目標應該是選擇與同一包中的其餘名稱一致且易於理解的名稱。其次是應該是選擇與更普遍的共識一致的名稱。避免使用較長的方法名。若是有疑問，能夠從Java類庫API中尋求指導。儘管類庫中也存在許多不一致之處(考慮到這些類庫的規模和範圍，這是不可避免的)，也提供了至關客觀的承認和共識。

不要過度地提供方便的方法。每種方法都應該「盡其所能」。太多的方法使得類難以學習、使用、文檔化、測試和維護。對於接口更是如此，在接口中，太多的方法使實現者和用戶的工做變得複雜。對於類或接口支持的每一個操做，提供一個功能完整的方法。只有在常用時，才考慮提供「快捷方式（shortcut）」。若是有疑問，請將其刪除。

避免過長的參數列表。目標是四個或更少的參數。大多數程序員不能記住更長的參數列表。若是你的許多方法超過了這個限制，若是未常常引用其文檔的狀況下，那麼你的API將沒法使用。現代IDE編輯器會提供幫助，可是使用簡短的參數列表仍然會更好。相同類型參數的長序列尤爲有害。用戶不只不能記住參數的順序，並且當他們意外地弄錯參數順序時，他們的程序仍然會編譯和運行。只是不會按照做者的意圖去執行。

有三種技術能夠縮短過長的參數列表。 一種方法是將方法分解爲多個方法，每一個方法只須要參數的一個子集。 若是不當心，這可能會致使太多方法，但它也能夠經過增長正交性（orthogonality）來減小方法個數。 例如，考慮java.util.List接口。 它沒有提供查找子列表中元素的第一個或最後一個索引的方法，這兩個索引都須要三個參數。 相反，它提供了subList方法，該方法接受兩個參數並返回子列表的視圖。 此方法能夠與indexOf或lastIndexOf方法結合使用，這兩個方法都有一個參數，以生成所需的功能。 此外，subList方法能夠與在List實例上操做的任何方法組合，以對子列表執行任意計算。 獲得的API具備很是高的功率重量( power-to-weight)比。

縮短過長參數列表的第二種技術是建立輔助類來保存參數組。這些輔助類一般是靜態成員類(條目24)。若是看到一個頻繁出現的參數序列表示某個不一樣的實體，建議使用這種技術。例如，假設正在編寫一個表示紙牌遊戲的類，而且發現不斷地傳遞一個由兩個參數組成的序列，這些參數表示紙牌的點數和花色。若是添加一個輔助類來表示卡片，並用輔助類的單個參數替換參數序列的每次出現，那麼API和類的內部結構可能會受益。

結合前兩個方面的第三種技術是，從對象構造到方法調用採用Builder模式(條目2)。若是你有一個方法有許多參數，特別是其中一些是可選的，那麼能夠定義一個對象來表示全部的參數，並容許客戶端在這個對象上進行多個「setter」調用，每次設置一個參數或較小相關的組。設置好所需的參數後，客戶端調用對象的「execute」方法，該方法對參數進行最後的有效性檢查，並執行實際的計算。

對於參數類型，優先選擇接口而不是類(條目64)。若是有一個合適的接口來定義一個參數，那麼使用它來支持一個實現該接口的類。例如，沒有理由在編寫方法時使用HashMap做爲輸入參數，相反，而是使用Map做爲參數，這容許傳入HashMap、TreeMap、ConcurrentHashMap、TreeMap的子Map（submap）或任何還沒有編寫的Map實現。經過使用的類而不是接口，就把客戶端限制在特定的實現中，若是輸入數據碰巧以其餘形式存在，則強制執行沒必要要的、代價高昂的複製操做。

與布爾型參數相比，優先使用兩個元素枚舉類型，除非布爾型參數的含義在方法名中是明確的。枚舉類型使代碼更容易閱讀和編寫。此外，它們還能夠方便地在之後添加更多選項。例如，你可能有一個Thermometer類型的靜態工廠方法，這個方法的簽名是如下這個枚舉：

public enum TemperatureScale { FAHRENHEIT, CELSIUS }

Thermometer.newInstance(TemperatureScale.CELSIUS)不只比Thermometer.newInstance(true)更有意義，並且能夠在未來的版本中將KELVIN添加到TemperatureScale中，而無需向Thermometer添加新的靜態工廠。 此外，還能夠將溫度刻度（temperature-scale）依賴關係重構爲枚舉常量的方法（條目34）。 例如，每一個刻度常量能夠有一個採用double值並將其轉換爲Celsius的方法。