摘要:
应用程序编程接口(API)提供对用于构建和集成应用程序软件复杂功能的访问。开发人员可以使用这些API提供的复杂功能,而无需修改或理解底层的实现细节。因此,开发人员倾向于在现有框架和库中重用API以促进开发过程。但是API通常很复杂且难以学习,因为它们可能包含数百个不同级别的元素(包、类和方法),并且包含复杂的依赖项。因此,各种类型的API文档提供了API的使用说明来帮助开发人员学习API,例如API规范,API教程,API众智文档,Wiki和博客。
然而目前尚不清楚不同类型的API文档在帮助开发人员学习API的难易程度上是否存在差异。本文中,我们以API官方教程和API众智文档为例,分析对比不同类型的API文档。API官方教程通常由API的设计者组织书写,API众智文档则来源于社交媒体,比如Stack Overflow。尽管这两种文档的来源不同,但是它们都提供了描述性语言和代码段来展示如何使用API。因此,我们的目标是分析比较API官方教程和API众智文档在帮助开发人员学习API的难易程度上是否有差异以及差异程度。
为了实现这个目标,我们在Java API文档和Android API文档上进行实验。我们从Oracle网站收集了1,062个Java官方教程,从Stack Overflow上收集了462,154个Java帖子。同时,我们从Android SDK中收集了181个Android官方教程,从Stack Overflow上收集了393,812个Android帖子。从Stack Overflow上收集的帖子经过问答对匹配,将问题和它的最佳答案进行组合构成API众智文档。然后我们从三个方面对API文档进行分析:API的覆盖率、API的关注度以及API文档格式。API的覆盖率能够分析开发人员能否通过参考API文档来了解API的使用。API的关注度能够说明API教程上的API和开发人员使用的API是否有差异。API文档格式揭示了API文档风格是否会影响开发人员学习使用API。因此,我们提出三个研究问题:
1.API官方教程和API众智文档对API的覆盖率分别是多大?
我们使用Recodoc工具将两种类型的API文档中的code-like terms链接到某个特定的API元素上(包、类或方法)。对于Java API,我们链接到Java SE 7 API,对于Android API,我们连接到Android library 7 API。基于每个API元素出现的频率,我们能够分析API文档对API元素的覆盖率。
2.API官方教程和API众智文档对API的关注度是否一致?
我们将API的排序或API排序百分比作为API关注度的一个指标。首先,我们根据每个API元素出现的频率对这些API降序排序,然后分别选取两种文档中top 15的API进行分析。另外我们也选取包含子类相对多的API包和API类,计算它们在不同文档中的排序百分比的差异值。若API元素的差异值超过50%,说明API官方教程和API众智文档对该API的关注度出现不匹配现象。
3.API官方教程和API众智文档在对API的解释上是否有差异,差异程度有多大?
我们首先通过调查问卷的形式分析API文档中的哪些特征有利于开发人员学习API。根据调查结果,我们使用Wilcoxon秩和检验来区分不同文档的特征是否有差异。同时,我们使用Spearman秩相关系数分析不同特征之间是否存在相关性,进而给API文档的设计者提供一些建议,使得API文档更能满足开发人员的需求。
经过分析,我们发现API众智文档对API的覆盖率高于API官方教程,因此开发人员可以参考API众智文档学习如何使用API。而且被API官方教程覆盖的大部分API都能够在API众智文档中找到相关解释,因此我们认为API众智文档可以作为API官方教程的补充来帮助开发人员学习API。我们还发现API的关注度在这两种文档中存在不一致现象。也就是说,API设计者和开发人员可能专注于不同的API,尤其对于细粒度的API元素,比如API方法。这可能导致开发人员找不到关于某个API的解释信息,降低他们学习API的效率。另外,我们发现长文本和链接有助于开发人员详细深入理解API的设计和使用。API官方教程有利于开发人员在同一页面搜索和学习API。API众智文档中的代码块有助于开发人员使用某些API完成特定的编程任务。这些特征能够被集成到新的API文档中,使得API文档能够更好地帮助开发人员学习使用API。