建立完美SDK的10個技巧

【編者按】本文做者爲 Gal Lavinsky，文中將列出10個零基礎小技巧，幫你建立完美的Java SDK。文章系國內 ITOM 管理平臺 OneAPM 編譯呈現。如下爲正文。

本文起源於筆者朋友的一次問詢。他認爲，關於如何寫好一個簡單易用的SDK，沒有足夠的參考文件。

在過去的十年裏，SDK的使用在開發生命週期中已經成爲了重要的一部分。事實上，它的使用和在產品中的集成已經如此常見，能夠說，相比於深度學習算法來自行實施，開發者們更須要學習大量框架以融會貫通。

本文主要面向想要學習書寫最佳SDK，併爲之提供參考文檔的讀者。SDK的出發點是它的參考文檔應當是重點明確且清晰的。若是你以爲文檔有多個重點，請考慮拆分爲多個文檔。

如下是筆者但願能幫助你更好地構建SDK並書寫其參考文檔的清單：

##1. 瞭解牆外的世界 試着去關注你的競爭對手或者與你類似領域的公司都作了什麼。這可能會給你一些參考的角度。採納你喜歡的地方，改善你不喜歡的地方。

##2. 簡潔 代碼簡潔——簡潔的代碼意味着你的客戶用起來駕輕就熟。這可能包括儘量減小與代碼交互的方式，好比只公開一個接口類；或是簡短的方法簽名，好比少許的輸入參數，等等。

除了初始化階段（只發生一次且可能要求進行配置），請讓SDK方法使用起來儘量簡單。

一樣地，請儘可能減小方法簽名中的參數。

你能夠經過提供默認配置以及容許高級用戶進行覆蓋的默認實現類來達到這一目的。

隱藏用戶不須要使用的類和方法，好比，只將用戶必須使用的類/方法設定爲公有的，不然就將它們的使用範圍設定爲局部或者私有。一個 IDEs 提供了代碼檢查與清除功能，能夠幫你自動實現這一點。

參考文檔簡潔——讓你的文檔儘量簡單易懂。這意味着有時候你得多寫註釋，有時候又得儘可能少寫。內聯樣本代碼一般頗有幫助，由於大多數人都是經過例子來學習的。

##3. 提供簡單的開始步驟 這是指一我的能夠在五分鐘內上手使用你的代碼。這一點很是重要，由於客戶每每但願儘量不費力地進行集成。除此以外，有時候客戶想要評估你的產品，但若是沒法進行簡單的測試，他們就極可能選擇跳過你的產品。

##4. 短小精悍 保持簡短主要是文檔的責任，可是一樣與用戶和SDK代碼的交互方式有關；爲了保持文檔的簡短，能夠提供代碼樣例、一目瞭然的方法名或使用默認數據來實現。

##5. 集成 請謹記客戶開發環境的多樣性。

好比說，若是你在寫一個安卓庫，它的集成方式在客戶使用Android Studio加gradle 框架和使用Eclipse集成開發環境時就很是不一樣。前者須要aar工件併發布到遠程存儲庫中，然後者須要你提供jar文件，以及關於如何爲SDK更改AndroidManifext.xml文件和獨立eclipse項目的指導。

這可能會影響你的構建機制及其工件。然而，不要試圖取悅全部客戶，請先知足你的第一位客戶，或者預期中的大多數客戶的需求。

##6. 項目示例 在GitHub上建立一個最基本的項目，模擬使用SDK包的用戶。

這能夠向客戶展現你的產品如何知足他們的需求，以及如何集成你的產品。若是你想展現高級用法，那就在另外一個項目裏進行展現。一般，客戶會將項目示例做爲主要的參考文檔，所以，請提供行內評論，並儘可能用一目瞭然的方式書寫代碼。

##7. 概述 在參考文檔的開頭，或是GitHub項目的README.md文件中，請用直白的語言對你的解決方案進行概述。在此部分，筆者一般會提供一個使用樣例來解釋SDK的典型用法。若是有可能，請提供一個簡單的表格或是圖表，這樣一來，不喜歡閱讀操做指南的用戶也能夠快速瞭解該SDK的優點。

##8. 初始化 使用在SDK域內可接受的慣例。

這些慣例多是可重載的構造函數，某種構建模式等。初始化應當巧妙地使用默認值來簡化流程。

##9. 默認值 默認值對於保持代碼的簡潔性和減小配置過程（見簡潔性部分）是很是重要的。你所提供的默認值（不論是在配置仍是實施過程）應該表明在你眼中大多數SDK用戶會進行的操做。

你能夠提供幾個方法重載，使最簡單的簽名均可以用默認值調用更高級的方法。

##10. 發佈

• 離線使用不可編輯模式——PDF。優點是文檔建立簡單，能夠本地存儲在Dropbox中。而且對於每次發佈，版本能夠自動更新。
• 在線——你的企業網站。這是更推薦的方式。然而，在更新時可能會致使一些額外的IT開銷。

但願這些指南對你有所幫助。也歡迎進行反饋。

OneAPM 能爲您提供端到端的 Java 應用性能解決方案，咱們支持全部常見的 Java 框架及應用服務器，助您快速發現系統瓶頸，定位異常根本緣由。分鐘級部署，即刻體驗，Java 監控歷來沒有如此簡單。想閱讀更多技術文章，請訪問 OneAPM 官方技術博客。

本文轉自 OneAPM 官方博客

原文地址：http://blog.mobitech.io/2016/02/sdk-writing-guidelines.html。