浅谈sdk的开发与设计

sdk，又称api，作为一种软件产品为程序员所熟知，为非程序员所陌生。
sdk作为一个对内面向程序员，对外面向程序员的产品，有着非常独特的开发和设计特点。sdk比任何一门语言都更像一门语言，完成程序员之间的交流。
sdk开发者清楚程序员需要的是什么。
一份可用的文档：
什么是可用的文档呢？准确。
程序员是一个很特殊的个体，不想写文档，但是又希望别的程序员提供文档，而且是高质量的可用的文档。优秀程序员为什么不愿意写文档呢，很简单，优秀的程序员一直秉持的一个编程信念就是：减少重复，而文档首先就是代码的重复。（其实注释也是一样的，优秀的程序员同样不喜欢写注释）。代码需要维护，文档同样需要维护，而这个持续的重复过程对有原则（减少重复）的优秀程序员来说是折磨。（没有人愿意持续违背自己的原则）。有鉴于此，没有文档，或者文档不能及时维护，就非常的普遍。那么我们可以理解为文档不可用，首先不能保证是准确的。
作为优秀的sdk开发人员，对此是游刃有余的（提供文档，并非sdk的开发人员不够优秀，其实也是无奈）。sdk的开发人员必须提供一份可用的文档，就像必须要有sdk一样。那么sdk的开发人员怎么解决这个问题呢？
1 文档从代码中自动化生成。这个不同的语言和平台有不同的方式方法，不做赘述。优秀的程序员首先考虑的是让自己的所有工作自动化，写文档这么low的事情肯定要自动化完成。文档主要来源于代码注释，刚刚提到优秀的程序员不喜欢写注释时不准确的，优秀的程序员不希望浪费自己的注释，必要的注释也是优秀程序员乐于撰写的。而这必要的注释首先就是公开部分的文档生成来源。
2 文档第一个读者。优秀的sdk开发人员是sdk的第一个使用者，也是文档的第一个读者。这个很重要，为什么这么说呢？sdk的开发人员清楚自己面向的是开发人员，加上开发人员有一种“文人相轻”的心态，总是不免降低姿态，考虑一个很low的程序员读自己的文档是否清楚的样子。因此优秀的sdk开发人员会积极的阅读自己的文档，以确保一个并不是很擅长编程的程序员也能使用sdk。
3 精简的文档。维护文档的工作量和文档的大小是成正比的。一个优秀的sdk开发人员会尽量减少文档的内容。其实这里的减少，不是裁剪，而是精简。减少重复，避免冗余，整洁的代码是这样的，优秀的程序员面对文档也是这个态度。
4 其实优秀的sdk开发人员这么尽职尽责的维护一份优秀的文档还有另外一个原因，避免使用人员的打扰。程序员是一个十分讨厌深恶痛绝被打扰的群体，（这是职业病，而且很重）。因此sdk的程序员宁可花一点时间维护好文档，减少不必要的麻烦。

一份可用的示例代码：
其实文档是首要的，但是不是必须的，大部分是无用的。这话只有程序员明白。开发文档大部分时候就像牛津大字典一样，大部分人不会先去背诵牛津大字典，然后再去读文章，读文章发现单词去查就好了。那么一份可用的示例代码就尤为重要。
什么是可用的示例代码呢？准确。
又一次提到准确，我也很意外，但是事实如此。程序员从网上拷贝代码已经不是什么稀罕的事情了，甚至无可厚非。那么写出一份可以供程序员拷贝的代码，真的还是很有技术含量的。不要笑，示例代码就是这样一份代码，它经常被拿来拷贝。程序员使用示例代码，第一是F5(对不起，我用vc太久了)，第二是control＋c、control＋v。因此示例代码无需任何处理，可以运行，不需要任何改变，直接可以拷贝，那真是太理想了。
作为优秀的sdk开发人员，对此是游刃有余的。这里我们采用和文档逆序的方式来述说吧。
1 程序员首先是害怕被别人打扰的，那么花时间维护一份可用的示例代码，而后就可以专心继续码代码而不被人打扰，真是一劳永逸。无奈有时候催生出好的产品。因此优秀程序员算清楚了这笔账，他乐于写出一份高效的示例程序。如果其他程序员使用了，神马，已经上线了，好吧，哈哈！
2 好的示例代码是符合优秀编程规范的。示例代码也是代码，优秀的程序员不会看不起示例代码（的确有一些程序员看不起示例代码）。写出一份高质量的示例代码也是需要很高水准的。规范的命名，模块化，小函数，异常检测，。。。好吧，其实我在编程，我在写代码，我喜欢写代码。
3 优秀的示例代码会弥补文档的缺陷。有时候文档是注释生成的，经常是干巴巴的接口描述。而优秀的示例代码会在进行接口调用的过程中通过清晰的代码结构和必要的说明来让其他程序员看清楚调用过程。并且对一些代码注意事项进行必要说明。

一份可用的接口：
好吧，sdk程序员终于可以做点程序员该做的事情了。那么一份可用的接口是什么样的呢？
好吧，其实只要优秀的设计就好了，真的没有开玩笑。
设计一个类，应该怎么设计呢，设计一个模块应该怎么设计呢，一个sdk也是。
相信有太多的书籍告诉我们怎么写出优秀的代码，一个可用的sdk接口首先是一个优秀的设计。这里我只想强调几个地方：
1 简，少。尽可能少，用其极。接口数量越少越好，接口参数越少越好，调用流程越少越好。越少越好，一是后续维护更加方便，少，需要维护的就少，文档改变就少，示例代码调整就少。另一方面，开发者用起来真是方便极了。没有买卖就没有伤害，精简的sdk让大家出bug的机会都少了好多。
2 自说明的代码。有时候真的可以没有注释和文档，好的程序是自说明的。我们不排除一些程序员连示例代码也没有看，就看着接口名称就开始写代码了。
3 提前报警。使用一些编程术语，让开发者在编程过程就发现错误，在调试阶段就暴露问题，施主功德无量啊。以c＋＋为例，我想说const再怎么使用也不过分，我在写接口参数时先写上这个关键字，然后再考虑是否要去掉。

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