• 如何构建完美 SDK的10大指南

    发布:51Code 时间: 2016-07-26 10:39

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

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

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

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

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

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

    1.简易

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

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

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

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

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

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

    2.提供一个轻松入门

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

    3.保持它简短化

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

    4.集成

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

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

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

    5.简单的工程

    在GitHub上创建一个最基本的工程,模拟一个客户正使用你的SDK的方式。

    这会给你的客户展示你的产品是如何满足他们的需求以及与你产品交互最简单的方式。如果你想展示一个更高级的使用方式,在另外一个工程中去展现吧。经常地,你的用户会将这个工程当作他们主要的文档来源来使用,那么,请提供内联的注释语句,并尽可能以自解释的方式写代码吧。

    6.概览

    在GitZHub工程的README.md文件中,开头的文档部分要使用简单的英语去提供关于你的解决方法的一个概览。在这部分,我通常喜欢提供一个示例来解释SDK的典型使用方法。如果可能,提供一个简单的图表,因为用户不喜欢读使用手册,这样他们可以很快获知你的SDK的优点。

    7.初始化

    在SDK领域使用约定惯例。

    它包含构造器重载,编译模式或者类似的约定。初始化应该有技巧地使用默认配置来保证一个轻松入门。

    8.默认选项

    为了保持代码简单和减少配置(请查看“简易”那一节)默认选项是很重要的。你提供的默认选项(不管是配置或实现)都应该展现一种方式,你认为你的大多数用户会如何使用SDK的方式。

    你可以提供几个方法重载,最简单的签名会缺省调用更高级的方法签名。

    9.发布

    · 线下使用不可编辑的格式--PDF。优势在于你能很简单地创建一个PDF,在本地Dropbox中保存,每当升级时,版本也会自动升级。

    · 线上--你公司的站点。这是一个推荐的方式,然而,每当你升级的时候,它会产生一个麻烦,会有一些IT方面的开支。


  • 上一篇:Android安全退出多个Activity的解决方案

    下一篇:移动应用丰富动效的六种通用方式

网站导航
Copyright(C)51Code软件开发网 2003-2021 , 沪ICP备05003035号-6