转载

构建完美SDK的10大技巧

英文原文： 10 Tips on How to Build the Perfect SDK

这篇博客起源于我一个朋友的咨询，他认为关于写一个好的 SDK，使得别人能够简单地使用方面，现在没有足够的文档。

过去十年来，SDK 使用已经变成了开发生命周期中一个重要的部分。事实上，它是如此常见地被使用并集成到产品中，以至于有人会说开发者需要去获取更多关于框架的知识而不是学习深入的算法知识来提升自我。

这篇博客主要是针对以下朋友，他们想要学习怎样去写最好的 SDK 并为它提供支持文档。一个 SDK 的目标或定位在于它的文档应该是聚焦的和清晰的。如果你发觉文档中的聚焦领域多余一个，考虑分开它吧！

构建完美SDK的10大技巧

下面是一个列表，我希望能帮你以一种良好的方式去构造一个 SDK，并编写它的文档：

0. 去获知那儿有什么东西

努力查看你的竞争者或公司在相似领域做了什么东西。这会给你一个参考点。拿走你喜欢的方面，改善你不喜欢的方面。

1. 简易

代码—-简单的代码意味着你的客户会发现它易于使用。这就包含与你代码尽可能少的交互方式，例如，只暴露一个接口类；简短的方法签名，例如，少量的输入参数个数，等等。

除了初始化函数以外，它只会出现一次并可能需要一些配置，让你的 SDK 方法的使用尽可能简单。

同样地，努力保持方法签名带有尽可能少的参数。

你可以通过提供默认配置和默认实现类来实现上面的目的，这些能被高级用户来重载修改。

隐藏任何用户不需要使用的类和方法，只有用户必须使用它们才将这些类或方法声明成公有，否则使用局部或私有域。一些开发环境能够使用代码检查和清除来帮助你自动实现上面功能。

文档：让你的文档尽可能简单。有时候这意味着写更多的解释性文字，而另外一些时候又意味着写尽可能少的文字。内联的代码示例经常会有所助益，因为大多数人通过例子来进行学习。

2. 提供一个轻松入门

一个简单的入门方式是那种让一些人在少于 5 分钟内就能使用你代码的方式。这点非常重要，因为用户想要尽可能少的集成时间，更甚者，有时候用户想要去评价你的产品，如果没有一种能力能够简单地做一个实验，他们很可能选择直接踢掉它。

3. 保持它简短化

这部分主要是关于文档的，但是它也与用户能够与 SDK 代码交互的方式相关。考虑到文档，通过提供代码示例和自解释性方法名称和使用默认设置可以实现简短化。

4. 集成

时刻记住，你的用户的开发环境是多种多样的。

例如，如果你正在写一个安卓库，将它集成起来的方式是多样化的，如果你的用户使用含有 gradle 脚本（它需要一个 arr 的史前配置，并会发布到一个偏僻的版本库）的 Android Studio，或者他们使用 Eclipse，这样就需要提供 jar 文件，提供关于如何修改 AndroidManifest.xml 文件的说明文档，以及一个单独的针对 SDK 的 eclipse 工程。

这会影响到你的编译机制，它就是一个史前古物。但是，不要想着头一天就解决所有问题。做些与你第一个客户或你预计的客户最匹配的工作。