Why and How Java Developers Break APIs (SANER 2018)

Why and How Java Developers Break APIs (SANER 2018)

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.

13beaa3b7239eca3319d54c6a9f3a85a?s=128

ASERG, DCC, UFMG

March 22, 2018
Tweet

Transcript

  1. 1.

    Why and How Java Developers Break APIs Aline Brito, Laerte

    Xavier, Andre Hora, Marco Tulio Valente SANER 2018
  2. 7.

    But, 28% out of 500K API changes break backward compatibility

    Historical and Impact Analysis of API Breaking Changes: A Large-Scale Study SANER 2017 7
  3. 10.

    APIDiff A tool to detect API Changes APIDiff: Detecting API

    Breaking Changes SANER Tool Track, 2018 https://github.com/aserg-ufmg/apidiff
  4. 11.

    APIDiff Breaking changes in types, methods, and fields • Removal

    • Change in access modifiers • Change in parameter list 11
  5. 12.

    APIDiff Breaking changes in types, methods, and fields • Removal

    • Change in access modifiers • Change in parameter list 12
  6. 13.

    APIDiff APIDiff warns if a breaking change is performed in

    internal or deprecated APIs io.reactivex.internal.util.ExceptionHelper 13
  7. 14.

    APIDiff APIDiff warns if a breaking change is performed in

    internal or deprecated APIs io.reactivex.internal.util.ExceptionHelper 14
  8. 15.
  9. 16.

    16 Top 2,000 projects by stars We discard projects without

    the keywords Library(ies), API(s), framework(s), and deprecated projects (449 projects) We inspect the projects documentation 400 libraries and frameworks
  10. 17.

    Top 2,000 projects by stars We discard projects without the

    keywords Library(ies), API(s), framework(s), and deprecated projects (449 projects) We inspect the projects documentation 17 400 libraries and frameworks
  11. 18.

    18 Top 2,000 projects by stars We discard projects without

    the keywords Library(ies), API(s), framework(s), and deprecated projects (449 projects) We inspect the projects documentation 400 libraries and frameworks
  12. 19.

    19 Top 2,000 projects by stars We discard projects without

    the keywords Library(ies), API(s), framework(s), and deprecated projects (449 projects) We inspect the projects documentation 400 libraries and frameworks
  13. 23.

    Study Steps We mined daily commits We used APIDiff to

    identify breaking changes We sent emails to developers asking the reasons behind changes 23
  14. 24.

    24 Study Numbers 116 days, May 8th to August 31th,

    2017 102 emails 56 answers (55%)
  15. 29.

    29 Survey Questions 1. Why did you perform these changes?

    2. Do you agree these changes can break clients? If yes, could you quantify the amount of work to use the new implementation? 3. Why didn’t you deprecate the old implementation? 4. Do you plan to document the changes? If yes, how?
  16. 32.
  17. 33.
  18. 40.

    Why do developers break APIs? 40 Motivation Description Occur. NEW

    FEATURE BCs to implement new features 19 API SIMPLIFICATION BCs to simplify and reduce the API complexity and number of elements 17 MAINTAINABILITY BCs to improve the maintainability and the structure of the code 14 BUG FIXING BCs to fix bugs in the code 3
  19. 41.

    New Feature (19 occurrences) “The changes in this commit were

    just a setup before implementing a new feature: chart data retrieval.” 41
  20. 42.

    Simplify API (17 occurrences) “This method should not accept any

    parameters, because they are ignored by server.” 42
  21. 46.

    Why don’t developers deprecate broken APIs? 46 Developers do not

    deprecate elements affected by BCs mostly due to the extra effort to maintain them.
  22. 47.

    Increase Maintainability Effort (8 answers) “In such a small library,

    deprecation will only add complexity and maintenance issues in the long run.” 47
  23. 50.

    What is the effort on clients to migrate? According to

    the surveyed developers, the effort to migrate to the new API versions is small. 50
  24. 57.

    Most unconfirmed BCCs affect internal or low-level APIs. 57 Implications

    to Language Designers However, internal APIs can be used by external clients, since they are public
  25. 59.

    59 Implications to Practitioners Many unconfirmed BCCs do not have

    internal or experimental in their names. Practitioners should use internal in low-level or internal API names
  26. 60.

    Why do Java developers break APIs? • New features •

    API simplification • Improve maintainability How do Java developers break APIs? • Move Method • Remove Class • Change in Parameter List • Rename Method • Move Class 60