浅谈SDK的开发与设计

SDK，全称：Software Development Kit，作为一种软件产品为程序员所熟知。

SDK由程序员开发，提供给程序员，有着非常独特的开发和设计特点。如果说语言是程序员与设备的交流，那么SDK完成程序员与程序员之间的交流。

开发SDK的程序员，往往需要作为程序员设身处地的思考，应该提供一个怎样的产品。

 

一份可用的文档：

为什么要有文档？

程序员大部分情况下并不喜欢写文档，而同时大部分情况下也不依赖文档。当然还是存在少数情况的，少数情况不是程序员喜欢写文档，而是依赖文档。如大部分程序员都有过在linux上man一个接口或help一个命令的体验。因此必要的文档还是必须的，提供文档也是一种专业的做法。

        有鉴于此，如果有文档，很多情况下，可能本来需要技术支持的事情不需要了。因此，花一点时间，可以省去很多麻烦。天知道，程序员是有多么的害怕被打扰。

那么应该如何维护文档呢？

        精简。维护文档的工作量和文档的大小是成正比的。SDK开发人员应该尽量减少文档的内容。其实这里的减少，不是裁剪，而是精简。减少重复，避免冗余，只提供必要的内容。想象一下SDK使用人员拿到你的SDK产品会希望从文档获取那些内容呢。

        自动化。SDK开发人员需要考虑文档的自动化生成，文档应该主要来源于代码注释(也许有一部分开发人员不喜欢写注释，但是必要的注释尤其对外公开的接口注释还是必须的，而这必要的注释也是文档生成来源。除此以外，文档的生成应该是伴随版本的构建流程的，即每个版本发布都自动更新文档。

        积极的阅读自己的文档。SDK开发人员是SDK的第一个使用者，也是文档的第一个读者。如果文档不能正确的传达所传达的信息，那么还不如没有。

 

一份可用的示例代码：

文档是必须的，大部分时间是无用的。开发文档大部分时候就像牛津大字典一样，大部分人不会先去背诵牛津大字典，然后再去读文章，读文章发现单词去查就好了。与之相反的是，一份可用的示例代码尤为重要。

       1 即时可用。SDK的使用人员拿到SDK，首先会运行示例代码（可能还没有读，示例代码阅读通常是伴随着运行发生的）。如果拿到的示例代码不能快速的进行编译运行，或者编译存在问题，运行失败，\(^o^)/，SDK的开发人员需要做好被频繁打扰的准备了。指导另一个程序员一步一步调通程序是令人恼火的，何况是一个接一个的呢。so，。。。

        2 正确且可拷贝。程序员从网上拷贝代码已经不是什么稀罕的事情了，甚至无可厚非。示例代码可用，然后control＋c、control＋v！我亲身经历过一个示例代码的一处错误，客户拷贝后带到发布的最终产品上，最后经过多方分析定位，找到是示例代码的原因。当时客户的程序员理直气壮的说，“可是，你们的示例是这样写的啊”。

        3 符合优秀编程规范的。示例代码也是代码，可能有些程序员看不起示例代码。写出一份高质量的示例代码也是需要很高水准的。规范的命名，模块化，小函数，异常检测，。。。好的示例代码能够让SDK使用者快速清楚代码的意图，同时也对SDK的开发人员能力产生信心。英雄惜英雄嘛。相反，拿到一份不堪入目的示例代码，天知道使用人员还有没有勇气使用SDK呢。

        4 弥补文档的缺陷。有时候文档是注释生成的，经常是干巴巴的接口描述。而优秀的示例代码会在进行接口调用的过程中通过清晰的代码结构和必要的说明来让其他程序员看清楚调用过程。并且对一些代码注意事项进行必要说明。

 

一份可用的接口：

好吧，SDK程序员终于可以做点程序员该做的事情了。其实SDK产品和其他软件产品的代码一样，需要一个好的设计和实现，关于如何写好代码的书籍一批一批的。简单说几点吧：

        1 简，少。尽可能少。接口数量越少越好，接口参数越少越好，调用流程越少越好。一是后续维护更加方便，少，需要维护的就少，文档改变就少，示例代码调整就少。二是开发者用着方便，精简的SDK让大家出bug的机会都少了好多。因此仔细看看头文件，是都需要的吗，这个接口应该可以删掉吧。

        2 统一的、自说明的接口。有时候真的可以没有注释和文档，好的程序是自说明的。我们不排除一些程序员连示例代码也没有看，就看着接口名称就开始写代码了。如果SDK提供了多个接口，那么做好给出统一而专业的接口名称吧。

        3 向后兼容。SDK产品往往是迭代的，向后兼容非常重要。使用SDK产品的人如果要升级，他希望一行代码也不要改，可以做到吗？

        4 定位与维护手段。错误码与日志，一方面客户调试过程方便协助，另一方面如果SDK存在未知问题也方便自己定位。

 

以己度人，SDK的开发人员，也许没有面对可恶的产品经理，变态的用户，但是在一个柳暗花明的地方遇见的是自己。