【编者按】本文作者为 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。
相关推荐
这个完美整合版包含了所有必要的组件,使得开发过程更为顺畅,无需用户自行搜集和整合各种资源。 一、SDK核心组件: 1. **Hammer编辑器**:Hammer是Valve的3D关卡设计工具,用于构建游戏地图。它支持多种视图操作,...
6. **创建菜单和命令**:在DLL中,使用CSCAD SDK提供的函数来创建菜单和命令条目。菜单可以是顶级菜单,也可以是子菜单,而命令则是菜单项点击后触发的动作。 7. **测试和调试**:在CSCAD中运行你的程序,查看菜单...
《VB2013完美代码库》是一本专注于VB.NET编程的实用资源,它包含了丰富的SDK信息和大量的实例程序,是VB.NET开发者不可多得的参考书籍。这本书旨在帮助开发者提高编程效率,解决实际问题,同时也适合作为初学者的...
首先,`ViewPager`是Android SDK提供的一种滑动页面视图容器,它允许用户通过左右滑动来浏览多个页面。`ViewPager`常用于实现类似TabLayout的效果,或者创建一个可以平滑滚动的多页界面。开发者可以通过设置`...
### Android PANIC Could not open my_avd.ini 完美解决方案 #### 问题描述 在尝试启动Android模拟器时,遇到了“PANIC: Could not open: my_avd.ini”这一错误提示。这个问题通常出现在配置环境变量或安装路径不...
在Android平台上,开发一款具有3D效果的相册应用是一项技术挑战,但通过巧妙的编程技巧和利用Android SDK中的特定组件,可以实现令人惊叹的视觉体验。本项目名为"android 3D相册完美实现",它展示了如何将普通的相册...
"Android高仿广告条用ViewPager实现左右完美无限滑动"这个标题指出,这是一个关于Android应用开发的项目,重点在于使用ViewPager组件来创建一个类似广告条的效果,该效果支持用户左右滑动查看内容,并且可以实现无限...
5. ** Mango SDK(软件开发工具包)**:SDK包含了模拟器、调试工具和其他必要的资源,帮助开发者创建、测试和优化应用程序。熟悉SDK的使用能加速开发进程。 6. **Live Tiles**:Windows Phone的动态磁贴是其独特的...
这个教程“安卓开发-Android高仿广告条用ViewPager实现左右完美无限滑动”显然关注的是如何利用ViewPager组件来打造这样一个功能。下面我们将深入探讨相关知识点。 **ViewPager** 是Android SDK中的一个强大组件,...
2. **点这里查看更多优质源码~.url**:这个文件名表明可能是一个链接,指向更多的Android源码示例或资源库,这对于开发者来说是一个宝贵的参考资料,可以拓展他们的知识面,学习更多Android开发技巧和最佳实践。...
ViewPager是Android SDK中的一个组件,常用于创建可滑动的页面视图,例如在引导页中展示多个屏幕。 压缩包内的文件名称列表包含了几个图片文件(可能是引导页的示例设计),一个文本文件(JavaApk源码说明.txt,...
1. **基础教程**: 包含如何安装和配置开发环境,以及创建第一个Windows Phone 7应用程序的步骤。 2. **进阶技术**: 可能涵盖数据存储、网络通信、多任务处理、地理位置服务、通知系统等高级主题。 3. **UI设计**: ...
在这个"Android高级应用源码-Android高仿广告条用ViewPager实现左右完美无限滑动.zip"中,我们可以深入学习如何使用ViewPager来构建一个高效、流畅且具有无限滚动特性的广告条。 首先,我们要理解ViewPager是...
2. **Android DrawerLayout**:这是Android SDK中内置的一个组件,用于创建抽屉式导航菜单,常与NavigationView一起使用。 3. **ActionBarSherlock**:这是一个扩展了Android Support Library的库,允许开发者在API...
《Android 完美高仿微信源码解析》 在移动应用开发领域,微信作为一个全球...通过深入研究这个源码,开发者可以提升自己的编程技巧,理解微信应用背后的架构设计,以及如何实现高效、稳定、用户体验优良的应用程序。
5. **优化和升级**:"完美版"可能意味着这个定时器解决方案已经过深度优化,提高了性能,减少了资源消耗,或者增加了更高级的功能,比如多线程支持、精确的时间控制、灵活的定时策略等。这可能涉及到对Windows底层...
在这个案例中,我们需要创建一个适配器,它包含所有广告图片的数据,并且能根据ViewPager的请求返回对应的页面。 4. **PageTransformer**:为了实现更酷炫的滑动效果,开发者可以使用PageTransformer接口。通过重写...
在本资源中,我们得到了一个"完美版的Android拼图游戏APK和工程源码",这是一套完整的安卓应用程序开发实例,对于学习Android应用开发,尤其是游戏开发的初学者或者开发者来说,这是一个非常宝贵的资源。下面将详细...
5. **使用Open XML SDK**:由于itext本身并不直接支持创建Word文档,我们通常会结合使用Microsoft的Open XML SDK,这是一个专门处理.docx文件格式的库。通过Open XML SDK,我们可以直接操作Word文档的XML结构,将...
例如,某些SDK可能需要在后台运行一个服务来处理复杂的计算,这显然增加了用户的使用门槛。为避免这种情况,开发者可以选择完全在本地进行人脸识别,或者寻找无需额外应用的轻量级解决方案,比如基于TensorFlow Lite...