Upgrade to Pro — share decks privately, control downloads, hide ads and more …

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.

ASERG, DCC, UFMG

March 22, 2018
Tweet

More Decks by ASERG, DCC, UFMG

Other Decks in Research

Transcript

  1. Why and How Java
    Developers Break APIs
    Aline Brito, Laerte Xavier, Andre Hora, Marco Tulio Valente
    SANER 2018

    View Slide

  2. Motivation
    Libraries have a key importance in modern software development
    200K libraries
    2

    View Slide

  3. Motivation
    Libraries have a key importance in modern software development
    200K libraries
    3

    View Slide

  4. Motivation
    Libraries have a key importance in modern software development
    200K libraries
    4

    View Slide

  5. Library services are provided via APIs
    5

    View Slide

  6. In theory, APIs should be stable
    6

    View Slide

  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

    View Slide

  8. Why do
    Developers
    Break APIs?
    8

    View Slide

  9. Outline
    1. APIDiff Tool
    2. Dataset
    3. Study Steps
    4. Definitions
    5. Results
    9

    View Slide

  10. APIDiff
    A tool to detect API Changes
    APIDiff: Detecting API Breaking Changes SANER Tool Track, 2018
    https://github.com/aserg-ufmg/apidiff

    View Slide

  11. APIDiff
    Breaking changes in types, methods, and fields
    ● Removal
    ● Change in access modifiers
    ● Change in parameter list
    11

    View Slide

  12. APIDiff
    Breaking changes in types, methods, and fields
    ● Removal
    ● Change in access modifiers
    ● Change in parameter list
    12

    View Slide

  13. APIDiff
    APIDiff warns if a breaking change is performed in internal or deprecated APIs
    io.reactivex.internal.util.ExceptionHelper
    13

    View Slide

  14. APIDiff
    APIDiff warns if a breaking change is performed in internal or deprecated APIs
    io.reactivex.internal.util.ExceptionHelper
    14

    View Slide

  15. Dataset

    View Slide

  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

    View Slide

  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

    View Slide

  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

    View Slide

  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

    View Slide

  20. Study Steps

    View Slide

  21. Study Steps
    We mined daily commits
    21

    View Slide

  22. Study Steps
    We mined daily commits
    We used APIDiff to identify breaking changes
    22

    View Slide

  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

    View Slide

  24. 24
    Study Numbers
    116 days, May 8th to August 31th, 2017
    102 emails
    56 answers (55%)

    View Slide

  25. Definitions
    25

    View Slide

  26. Breaking Changes Candidates (BCC)
    Changes detected by APIDiff in public API elements
    26

    View Slide

  27. Breaking Changes (BC)
    BCCs confirmed by the surveyed developers
    27

    View Slide

  28. Survey Results
    28

    View Slide

  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?

    View Slide

  30. Q1: How often do changes impact clients?
    30

    View Slide

  31. How often do changes impact clients?
    59 BCCs (39%) detected
    by APIDiff are BCs
    31

    View Slide

  32. Unconfirmed Breaking Changes
    92 changes (61%)
    The surveyed developers did not agree
    they have an impact on clients
    32

    View Slide

  33. Unconfirmed Breaking Changes
    Most unconfirmed BCCs are in internal
    or low-level APIs or in testing branches
    33

    View Slide

  34. Most common breaking changes
    34

    View Slide

  35. Most common breaking changes
    Most BCs are due to refactorings (47%)
    35

    View Slide

  36. Most common breaking changes
    36

    View Slide

  37. Breaking changes per API element
    37

    View Slide

  38. Breaking changes per API element
    Most BCs are performed on
    methods (59%)
    38

    View Slide

  39. Q2: Why do developers break APIs?
    39

    View Slide

  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

    View Slide

  41. New Feature (19 occurrences)
    “The changes in this commit were just a setup before
    implementing a new feature: chart data retrieval.”
    41

    View Slide

  42. Simplify API (17 occurrences)
    “This method should not accept any parameters,
    because they are ignored by server.”
    42

    View Slide

  43. Maintainability (14 occurrences)
    “Make support class lighter, by moving methods to
    Class and Method info.”
    43

    View Slide

  44. Q3: Why don’t developers deprecate
    broken APIs?

    View Slide

  45. Why don’t developers deprecate broken APIs?
    45
    (17 answers)

    View Slide

  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.

    View Slide

  47. Increase Maintainability Effort (8 answers)
    “In such a small library, deprecation will only add
    complexity and maintenance issues in the long run.”
    47

    View Slide

  48. Q4: What is the effort on clients to migrate?

    View Slide

  49. What is the effort on clients to migrate?
    49

    View Slide

  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

    View Slide

  51. Q5: How do developers document
    breaking changes?
    51

    View Slide

  52. Do you plan to document the changes?
    14 developers 4 developers
    52

    View Slide

  53. How do developers document BCs?
    53

    View Slide

  54. How do developers document breaking changes?
    54

    View Slide

  55. How do developers document breaking changes?
    55

    View Slide

  56. Implications and Conclusions
    56

    View Slide

  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

    View Slide

  58. *http://openjdk.java.net/projects/jigsaw
    58
    Implications to Language Designers
    This confirms the relevance of the new module
    system, being proposed to Java

    View Slide

  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

    View Slide

  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

    View Slide

  61. Thank you!
    Aline Brito, Laerte Xavier, Andre Hora, Marco Tulio Valente
    SANER 2018

    View Slide