給年輕程式設計師的33條忠告
阿新 • • 發佈：2018-12-14
- 你的 API 是有使用者的，因此它有使用者體驗。在你做的每一個決定中，都要考慮到使用者。要站在使用者的角度思考問題，無論他們是初學者還是有經驗的開發人員。
- 要保持讓你使用者使用 API 的過程中儘量減少認知負荷。自動化可以自動化的東西，最小化使用者需要的操作和選擇，不要顯示不重要的選項，設計簡單一致的工作流，反映簡單一致的思維模型。
- 簡單的事情要簡單的處理，複雜的事情應該儘量簡單化。不要為了小範圍的用例而增加普通用例的認知負荷，即使是最低限度的。
- 如果工作流的認知負載足夠低，那麼使用者在完成一到兩次工作之後，應該可以靠記憶完成工作了 (無需查詢教程或文件)。
- 尋求與領域專家和實踐者的心智模型相匹配的 API。有領域經驗但沒有 API 經驗的人應該能夠使用最少的文件直觀地理解你的 API，主要是通過檢視一些程式碼示例，看看哪些物件可用，以及它們的特徵是什麼。
- 一個引數的含義應該是容易理解的，而不需要任何關於底層實現的上下文。必須由使用者指定的引數應該與使用者關於問題的心理模型相關，而不是與程式碼中的實現細節相關。一個 API 是關於它解決的問題，而不是關於軟體在後臺如何工作。
- 最強大的心智模型是模組化和層次化的: 在高層次上很簡單，但在細節上很精確。同樣地，一個好的 API 是模組化和層次化的: 易於使用，但具有表現力。在更少的物件上有複雜的特性和具有更簡單特性的物件之間有一個平衡。一個好的 API 有合理數量的物件，具有相當簡單的特性。
- 你的 API 不可避免地反映了你的實現選擇，特別是你對資料結構的選擇。要實現直觀的 API，你必須選擇自然適合其領域的資料結構——與領域專家的心智模型相匹配。
- 特意設計端到端工作流，而不是一組原子特性。大多數開發人員在進行 API 設計時都會問: 應該提供哪些功能? 讓我們為它們提供配置選項。恰恰相反，他們應該這樣問: 這個工具的用例是什麼? 對於每個用例，使用者操作的最佳順序是什麼? 支援這個工作流的最簡單的 API 是什麼? 你的 API 中的原子選項應該能夠滿足在高階工作流中出現的明顯需求——它們不應該被新增，“因為有人可能需要它”。
- 錯誤訊息，以及在與 API 互動過程中向用戶提供的任何反饋，都是 API 的一部分。互動性和反饋是使用者體驗的一部分。需要謹慎的設計 API 的錯誤訊息。
- 因為程式碼是一種交流方式，所以命名很重要——無論是命名專案還是變數。名字反映了你對問題的看法。避免使用過於通用的名稱 (x、變數、引數)，避免使用過於冗長和特定的命名模式，避免使用可能造成不必要誤解的術語 (主、從)，並確保你的命名選擇方式是一致的。命名一致性意味著內部命名一致性 (不要在其他地方將“dim”稱為“axis”) 和與問題域的既定約定的一致性。在確定名稱之前，請確保查詢領域專家 (或其他 API) 使用的現有名稱。
- 文件是 API 使用者體驗的中心。它不是一個附加元件。著力產出高質量的文件；你將看到比開發更多的功能更高的回報。
- Show, don 't tell：你的文件不應該討論軟體是如何工作的，它應該展示如何使用它。顯示端到端工作流的程式碼示例；為你的 API 的每個常見用例和關鍵特性展示程式碼示例。