程式庫作者準則簡介

這份指南包含了設計程式庫時應考慮的最佳實務與構想摘要。

為了發揮效用，程式庫必須達成特定的基本目標。具體而言，它應該：

• 定義其問題領域，並實作一組相關的功能需求，以解決其定義的問題。 例如，HTTP 用戶端可能旨在支援所有 HTTP 請求類型，並能理解各種標頭 (header)、內容型別 (content type) 及狀態碼。

• 符合適合該問題領域的非功能性標準。這些通常涉及效能、可靠性、安全性及可用性。 這些標準的相對重要性差異很大。例如，為批次處理設計的程式庫，其效能要求可能與用於當沖交易 (day trading) 的程式庫不同。

  識別與定義功能性及非功能性需求的過程是一個複雜的主題，在軟體工程中已被廣泛研究。 這份指南不會深入探討這些主題，因為它們超出了其範圍。

本指南的主要焦點在於探討程式庫必須具備哪些特性，才能與使用者保持相關性並受到歡迎。這些特性包括：

• 最小化心智複雜度： 所有開發人員都必須考慮程式碼的可讀性與可維護性。降低他人閱讀、理解及使用您的 API 所需的心智負擔至關重要。達成此目標的方法是建立清晰、一致、可預測且易於偵錯的程式庫。
• 回溯相容性： 發佈 API 的新版本時，請確保現有的 API 仍能運作。提前清楚地溝通並記錄任何重大變更 (breaking changes)。為使用者提供一條直接、明確且漸進的路徑，以採用新的 API 或設計變更。
• 資訊豐富的文件： 程式庫隨附的文件需要做的而不僅僅是重複函式與型別宣告。它應該是全面的，且專門為程式庫的受眾量身打造。它應準確反映各種使用者角色的需求與情境，確保提供必要資訊，同時不會過於簡單或複雜。請務必包含清晰的範例，在說明文字與實用的程式碼範例之間取得平衡。

此外，為您的 Kotlin 程式庫建置多平台支援可以擴大其在針對各種環境的專案中的適用性。將 API 設計為能在共用與特定平台程式碼中可靠地運作，可以提高程式庫在所有受支援目標上的通用性與可用性。

以下章節將深入探討這些特性，並提供有關如何為您的程式庫使用者提供最佳體驗的實用建議。

接下來的步驟

• 在最小化心智複雜度中探索最小化心智複雜度的策略。
• 在回溯相容性中學習維護回溯相容性的相關知識。
• 有關有效文件實務的詳盡概述，請參閱資訊豐富的文件。
• 在為多平台建置 Kotlin 程式庫中探索建置多平台程式庫的最佳實務。