On the use of replacement messages in API deprecation: An empirical study

Libraries are commonly used to support code reuse and increase productivity. As any other system, they evolve over time, and so do their APIs. Consequently, client applications should be updated to benefit from better APIs. To facilitate this task, API elements should always be deprecated with replacement messages. However, in practice, there are evidences that API elements are deprecated without these messages. In this paper, we study questions regarding the adoption of deprecation messages. Our goal is twofold: to measure the real usage of deprecation messages and to investigate whether a tool is needed to recommend them. We assess (i) the frequency of deprecated elements with replacement messages, (ii) the impact of software evolution on this frequency, and (iii) the characteristics of systems that deprecate API elements in a correct way. Our analysis on 622 Java and 229 C# systems shows that: (i) on the median, 66.7% and 77.8% of the API elements are deprecated with replacement messages per project, (ii) there is no major effort to improve deprecation messages, and (iii) systems that deprecated API elements with messages are different in terms of size and community. As a result, we provide the basis for creating a tool to support clients detecting missing deprecation messages.