Why and How Java Developers Break APIs

TL;DR

This study investigates why and how Java developers introduce breaking changes in APIs, revealing key motivations and providing insights for improving API stability and evolution.

Contribution

The paper presents a detailed field study of 400 Java libraries, identifying main reasons for breaking changes and offering practical suggestions for API evolution.

Findings

Breaking changes are mainly motivated by new features, simplification, and maintainability.

19 projects confirmed the 59 identified breaking changes.

Developers' explanations clarify the decision-making process behind breaking changes.

Abstract

Modern software development depends on APIs to reuse code and increase productivity. As most software systems, these libraries and frameworks also evolve, which may break existing clients. However, the main reasons to introduce breaking changes in APIs are unclear. Therefore, in this paper, we report the results of an almost 4-month long field study with the developers of 400 popular Java libraries and frameworks. We configured an infrastructure to observe all changes in these libraries and to detect breaking changes shortly after their introduction in the code. After identifying breaking changes, we asked the developers to explain the reasons behind their decision to change the APIs. During the study, we identified 59 breaking changes, confirmed by the developers of 19 projects. By analyzing the developers' answers, we report that breaking changes are mostly motivated by the need to implement new features, by the desire to make the APIs simpler and with fewer elements, and to improve maintainability. We conclude by providing suggestions to language designers, tool builders, software engineering researchers and API developers.