附录：外文参考文献及翻译

Do Developers Deprecate APIs with Replacement Messages? A Large-Scale Analysis on Java Systems

G Brito，A Hora，MT Valente，R Robbes
Published in International Conference on Software Analysis, 2016:1-10

As any other software system, frameworks and libraries evolve over time, and so their APIs. Consequently, client systems should be updated to benefit from improved APIs. To facilitate this task and preserve backward compatibility, API elements should always be deprecated with clear replacement messages. However, in practice, there are evidences that API elements are usually deprecated without such messages. In this paper, we study a set of questions regarding the adoption of deprecation messages. Our goal is twofold: to measure the usage of deprecation messages and to investigate whether a tool is needed to recommend such messages. Thus, we verify (i) the frequency of deprecated elements with replacement messages, (ii) the impact of software evolution on such frequency, and (iii) the characteristics of systems which deprecate API elements in a correct way. Our large-scale analysis on 661 real-world Java systems shows that (i) 64% of the API elements are deprecated with replacement messages per system, (ii) there is almost no major effort to improve deprecation messages over time, and (iii) systems that deprecated API elements in a correct way are statistically significantly different from the ones that do not in terms of size and developing community. As a result, we provide the basis for the design of a tool to support client developers on detecting missing deprecation messages.

Introduction

Nowadays, it is common practice to implement systems on top of frameworks and libraries [1], taking advantage of their Application Programming Interfaces (APIs) to reuse functionalities [2] and increase productivity [3]. However, as any other software system, frameworks/libraries and their APIs are subjected to evolve over time. Naturally, public types, methods and fields provided by such APIs may be renamed, removed or updated. Consequently, client systems should migrate to benefit from improved API elements. To facilitate client developers making the transition and preserve backward compatibility, API elements should always be deprecated with replacement messages. Mechanisms to support API deprecation are provided by most of the programming languages. For example, Java has two solutions to deprecate types, methods, and fields: using deprecation annotations and/or deprecation Javadoc tags. Both annotations and Javadoc tags warn developers referencing deprecated APIs, however, the latter may be accompanied by replacement messages to suggest what to use instead. Ideally, APIs should use these mechanisms to assist client developers. In practice, previous studies indicate that API elements are often deprecated with missing or unclear replacement messages [4]–[6]. However,we are still unaware about the size of this phenomenon and whether it tends to get better (or worse) over time. In this paper, we study a set of questions regarding the adoption of API deprecation messages. We analyze (i) the frequency of deprecated API elements with replacement messages, (ii) the impact of software evolution on such frequency, and (iii) the characteristics of systems which deprecate API elements in a correct way in terms of popularity, size, community, activity and maturity. Our goal is twofold: to measure the usage of deprecation messages and to investigate whether a tool is needed to recommend such messages. Thus, we investigate the following research questions to support our study: bull; RQ1. What is the frequency of deprecated APIs with replacement messages? bull; RQ2. What is the impact of software evolution on the frequency of replacement messages? bull; RQ3. What are the characteristics of software systems with high and low frequency of replacement messages? In this study, we provide a large-scale analysis on 661 realworld Java systems. Our results show that (i) 64% of the API elements are deprecated with replacement messages per system, (ii) there is almost no major effort to improve deprecation messages over time, and (iii) systems that deprecated API elements in a correct way are statistically significantly different from the ones that do not in terms of size and developing community. As a result, we provide the basis for the design of a tool to support client developers on detecting missing deprecation messages. Thus, the contributions of this paper are summarized as follows: bull; We provide a large-scale study to better understand to what extend APIs are being deprecated with replacement messages. bull; We provide the motivati

剩余内容已隐藏，支付完成后下载完整资料

Java系统API分析

G Brito，霍拉山，MT Valente，R Robbes

发表在软件分析国际会议， 2016:1-10

随着任何其他的软件系统，框架和库随着时间的推移演变，所以他们的API客户端系统应该更新，以受益于改进的API。为了推动这项工作，保持向后兼容性，API元素应该被明确的置换信息。然而，在实践中，有证据显示API元素通常是过时的没有这样的消息。在本文中，我们研究了一套关于反对收养问题的消息。我们的目标是双重的：测量信息的使用和折旧是否需要工具来推荐这样的消息。因此，我们验证推荐使用元素替换消息的频率，（1）软件演化对频率的影响，（2）系统取代API元素以正确的方式的特点。我们对现实世界的661个java系统大规模的分析表明，API元素64%是过时的每个系统更换的信息，（3）几乎没有大的努力提高折旧信息随着时间的推移，（4）系统使用API元素以正确的方式有着显著

的不同，不在从规模和发展社区的。因此，我们对一个工具的设计支持客户端开发人员在检测缺失贬低消息提供依据。

1.简介

如今，它是常见的做法，实现系统之上的框架和库[ 1 ]，利用他们的应用程序编程接口（API）重用功能[ 2 ]和提高生产力[ 3 ]。然而，与任何其他的软件系统一样，框架/库和它们的API随着时间的推移而进化。当然，这些API提供的公共类型、方法和字段可以重命名、删除或更新。因此，客户端系统应该迁移到受益于改进的API元素。为了方便客户开发商转型和保持向后兼容性，API元素应该被更换的消息。的机制来支持API贬低大多数的编程语言提供了。例如，java已经弃用的类型、方法和字段的两个解决方案，使用贬低注释和/或贬低的Javadoc标签。注释和javadoc标签警告开发商引用过时的API，但是，后者可能伴随置换信息建议用什么代替。理想情况下，API应该使用这些机制来帮助客户端开发人员。在实践中，以往的研究表明，使用API元素往往缺少或不清楚–更换消息[ 4 ] [ 6 ]。然而，我们仍然不知道这种现象的大小，以及它是否会变得更好（或更坏）随着时间的推移。在本文中，我们研究了一套关于API消息通过折旧问题。我们分析了不支持的API元素置换消息的频率，（ii）软件演化对频率的影响，及（iii）系统取代API元素以正确的方式在人气方面，大小、群落特征、活动和成熟。我们的目标是双重的：测量信息的使用和折旧是否需要工具来推荐这样的消息。因此，我们研究以下问题来支持我们的研究：bull;RQ1。频率不赞成使用的API与更换的消息是什么bull;RQ2。软件进化对替换消息的频率的影响是什么？bull;rq3。具有高和低频率的替换消息的软件系统的特点是什么？在这项研究中，我们提供了一个大规模的分析661实际java系统。我们的研究结果表明，的API元素64%是过时的每个系统更换的信息，（ii）几乎没有大的努力提高折旧信息随着时间的推移，和（iii）系统，使用API元素以正确的方式有着显著的不同，不在规模和发展社区那些。因此，我们对一个工具的设计支持客户端开发人员在检测缺失贬低消息提供依据。因此，本文的主要贡献如下：bull;我们提供了一个大规模的研究来更好地理解什么扩展API deprecated更换信息。bull;我们提供的动机，需要一个推荐工具，以帮助客户端开发人员在检测丢失的替换消息。结构的文件：在第二节中，我们提出的背景更详细。我们描述我们的实验设计在第三节中，我们提出了实验结果在第四节的总结和影响，如第五节和威胁的有效性在第六节。最后，我们提出了相关的工作在第七节，我们得出结论，在第七节的文件。

2.背景

我们定义了一个API元素作为一个公共/受保护的类型，字段或方法。在理论上，取代之前，API元素应该被标记为过时的支持客户端开发者制作新的过渡。过时的API元素继续在系统维护向后兼容性，但他们不应该被开发商因为他们未来可能会删除。java已经弃用的类型、方法和字段的两个解决方案，使用注释@弃用（支持从J2SE 5），和/或使用Javadoc标签@弃用（支持从J2SE 1.1），如图1。标注“不使编译器发出警告，当它发现引用过时的API元素。Javadoc标签”不赞成的元素也警告开发商。然而，其相关的Javadoc注释可能伴随消息建议开发者使用什么相反，即更换的消息。java贬低的指南创建消息这些替代两个解决办法：1.1：使用bull;javadoc注释“看指示更换API。bull;javadoc 1.2及以后：用词的使用遵循注释”链接显示替代的API（如图1所示）。注意，然而，java贬低指南不是强制性的规定：开发商可采取其他惯例产生置换信息，或根本不使用它们。理想情况下，一个API元素应该被废弃和贬低的诠释，贬低Javadoc标记，以替代短信支持开发者迁移到新的/更好的。然而，在实践中，以往的研究表明，使用API元素往往缺少或不清楚–更换消息[ 4 ] [ 6 ]。在这项工作中，我们验证了在一个大型的水平（我）不支持的元素与java系统的更换消息的频率，这频率（II）是否增加或减少随着时间的推移，（III），所贬的API元素以正确的方式系统的特点。

实验设计

A.选择案例研究

我们分析了java系统托管在GitHub的流行社会编码平台。我们用三个标准来选择系统：恒星、发布数量，和过时的API元素。

（1）恒星数。GitHub提供的星星，让用户对系统感兴趣的特征数。我们选择了100个或更多为了过滤现实和流行的在GitHub的恒星系统。

（2）发行数量。我们选择了三个或更多的公开发布在GitHub上的系统。我们用这个标准来评估API贬低进化。

（3）一些过时的API。我们选择一个或多个公共/系统保护过时的API元素。我们用这个标准来过滤掉没有过时的元素系统。这些系统不在我们的研究范围之内。

基于上述过滤标准，我们选择了661个系统。为了更好地描述这样的系统，图2提出了分布的三个标准。对于恒星数，第一个四分位数，中位数，和第三个四分位数分别为154，279，和分别。更多的星星前系统弹性/ Elasticsearch（12.4k星），nostra13 / Android universalimage装载机（9.7k），和谷歌/ iosched（7.7k）。对于释放的数量，第一个四位数，中位数，和第三个四分位数为11，24，和57。更多的释放前系统JetBrains /科特林级（2.9k发布），RStudio / RStudio（2.1k），和Freenet /弗莱德（1.9k）。最后，对已过时的API元素个数，第一个四分位数，中位数和第三分位数是3，12，和39。更不赞成的API是常规/常规日食前系统（2.3k过时的API），OpenMRS / OpenMRS核心（1.2k），和opengamma / OG平台（994）。

B.提取过时的API元素

支持回答研究问题的第一步，我们提取所有过时的API元素（类型、字段和方法）和其相关联的Javadoc从系统分析。在第二节中，一个java API元素可以不使用注释“过时的或废弃的javadoc标签”。找到过时的API元素，我们实现了一个解析器基于Eclipse JDT图书馆找贬低注释和标签,我们限制我们的分析，公共的和受保护的API元素，因为他们代表客户外部合同。我们提取了5802个过时的类型，4427过时的领域，和26890个过时的方法，相应的37119个过时的API元素。

C.提取置换信息过时的API元素

当一个方法被弃用的Javadoc标签，它可能会伴随着一个置换信息帮助客户开发。在第二节，java的指南创建折旧置换信息两种解决方案：（一）使用注释”看，或（ii）使用的用词和注释”链接。然而，在实践中，开发人员可能采用其他指南来创建替换消息或根本不使用任何API.

检测方案的指导方针，我们提取折旧信息过时的API元素与JDT库的支持，我们手动检查这些信息的一个子集。作为这样的手动分析的结果，我们发现，除了字的使用，三频繁的字/模式，以指示更换：引用，等价，替换*（即更换，更换，更换），见，移动，而应使用。我们还确认了两个经常采用的注释：@链接和@参见。表i显示每个替换指南的频率以及消息示例。采用最多的就是用词：17810例，它发生在废弃的API元素47.9%。与此相反，应采用最少的准则：33例，它只发生在0.09%。请注意，一些准则可能一起出现在同一消息。例如，通常使用@链接。总的来说，22075（59.5%）API元素被弃用的所有37119个置换的消息。这些数据进一步探索研究问题1，其演变分析研究问题2。

D.定义指标可能影响API的贬低

支持回答研究问题3，关于系统API元素置换反对消息的特点，我们确定的指标，可能会影响到发展实践的五个维度：系统的普及，大小，社区，活动，和成熟。这个想法是要探讨这些指标对开发人员认为API元素的影响。这些尺寸和度量如下所述，并在表二中总结。

E.从案例研究中提取度量

我们提取了该指标从两组系统：那些贬低的API元素以正确的方式和那些不这样做。然后，我们评估了这样的群体，以验证他们是否有统计学差异的建议指标。这两个步骤详细如下。选择系统和提取度量。我们把所有的系统，依次，基于过时的API元素置换消息的百分比。我们选择了两组，25 %（即系统与不支持的API元素置换信息比例最高）和bottom-25 %（即系统的最低百分比）。每组有166个系统。图3显示不支持的API元素每组更换消息的百分比分布。顶部系统的中位数百分比为100%，底层系统为12.5%。最后，我们提取的指标，在上一段的顶部和底部系统。

总结

A.频率不赞成使用的API与更换的消息是什么？我们分析了过时的API元素类型、更换频率等信息，并在案例研究的最后一个版本的方法。如表III，3825（65.9%）不包含更换消息类型。对废弃的字段和方法，这些数字是2621（59.2%）和15629（58.1%），分别为。考虑到所有过时的API元素，22075（59.5%）包含置换信息。

B. RQ2。软件进化对替换消息的频率的影响是什么？为了验证软件演化对折旧的影响，我们分析了过时的API元素置换消息的频率在两个不同的版本的系统。我们比较第一个公开发行与最后一个（即，相同的研究问题1）。考虑的第一个和最后一个版本，我们发现10798和22075已过时的API元素置换信息，分别。绝对分析。图6显示不支持的API元素每更换系统信息的绝对数量的分布，在分析发布。在第一个版本中，第一个四分位数为1，中位数为3，而四分位数为17。在最后一个版本中，第一个四分位数为1，中位数为5，四分位数为18。注意，不支持的API元素置换信息随时间增加的绝对数的中位数（3至5）。事实上，这是预期的自然进化的系统，这可能提供更多的功能。

剩余内容已隐藏，支付完成后下载完整资料

资料编号：[25517]，资料为PDF文档或Word文档，PDF文档可免费转换为Word