When Should Internal Interfaces be Promoted to Public? (FSE 2016)

When Should Internal Interfaces be Promoted to Public? (FSE 2016)

Commonly, software systems have public (and stable) interfaces, and internal (and possibly unstable) interfaces. Despite being discouraged, client developers often use internal interfaces, which may cause their systems to fail when they evolve. To overcome this problem, API producers may promote internal interfaces to public. In practice, however, API producers have no assistance to identify public interface candidates. In this paper, we study the transition from internal to public interfaces. We aim to help API producers to deliver a better product and API clients to benefit sooner from public interfaces. Our empirical investigation on five widely adopted Java systems present the following observations. First, we identified 195 promotions from 2,722 internal interfaces. Second, we found that promoted internal interfaces have more clients. Third, we predicted internal interface promotion with precision between 50%–80%, recall 26%–82%, and AUC 74%–85%. Finally, by applying our predictor on the last version of the analyzed systems, we automatically detected 382 public interface candidates.

13beaa3b7239eca3319d54c6a9f3a85a?s=128

ASERG, DCC, UFMG

November 15, 2016
Tweet

Transcript

  1. When Should Internal Interfaces Be Promoted to Public? André Hora,

    Marco Tulio Valente, Romain Robbes, Nicolas Anquetil FSE 2016
  2. Outline 1.Context 2.Problem 3.Study Design 4.Results 5.Final Remarks 2

  3. Software Evolution Software systems are under constant evolution New features,

    bug-fixes, refactoring Up to 90% of development costs 3
  4. Library Evolution 4

  5. API Evolution Good Practices 1. API developers should deprecate API

    elements with clear replacement messages to facilitate migration 2. API clients should only use public and stable APIs to avoid backward-incompatibility 5
  6. API Evolution Good Practices 1. API developers should deprecate API

    elements with clear replacement messages to facilitate migration 2. API clients should only use public and stable APIs to avoid backward-incompatibility ✖ [Robbes et al., 2012, Brito et al. 2016] 6
  7. API Evolution Good Practices 1. API developers should deprecate API

    elements with clear replacement messages to facilitate migration 2. API clients should only use public and stable APIs to avoid backward-incompatibility 7
  8. Public Interfaces Stable, Supported, Documented Clients can use eg: java.util.List

    8
  9. Public Interfaces Stable, Supported, Documented Clients can use eg: java.util.List

    Internal Interfaces Unstable, Unsupported, Undocumented Clients should not use eg: org.eclipse.jdt.internal.ui.JavaPlugin 9
  10. Examples of Internal Interfaces org.eclipse.jdt.internal.ui.IJavaHelpContextIds org.junit.internal.AssumptionViolatedException org.junit.internal.runners.InitializationError org.hibernate.internal.util.ReflectHelper org.hibernate.internal.CoreMessageLogger sun.misc.Unsafe

    10
  11. Examples of Internal Interfaces org.eclipse.jdt.internal.ui.IJavaHelpContextIds org.junit.internal.AssumptionViolatedException org.junit.internal.runners.InitializationError org.hibernate.internal.util.ReflectHelper org.hibernate.internal.CoreMessageLogger sun.misc.Unsafe

    *.internal.* sun.* 11
  12. “Packages containing implementation details have internal in the name. They

    are unsupported and subject to change. Client code must never reference internal elements.” “sun.* packages are not part of the supported, public interface. Writing java programs that rely on sun.* is risky: those classes are not portable, and are not supported.” Java Documentation Eclipse Documentation 12
  13. Outline 1.Context 2.Problem 3.Study Design 4.Results 5.Final Remarks 13

  14. 44% of 512 Eclipse clients use internal interfaces [Businge et

    al., 2013] Clients often use internal interfaces! 14
  15. 23% out of 9,702 Eclipse clients use internal interfaces (45K

    files) [Boa Infrastructure] Ultra-large scale level Clients often use internal interfaces! 44% of 512 Eclipse clients use internal interfaces [Businge et al., 2013] 15
  16. Internal interfaces may become Public Eclipse client asks: “CharOperation is

    technically internal but it seems generally useful enough to use elsewhere. I would like to see it made public.” Eclipse developer answers: “We could indeed surface it into a public package” 16
  17. Internal interfaces may become Public Eclipse client asks: “CharOperation is

    technically internal but it seems generally useful enough to use elsewhere. I would like to see it made public.” Eclipse client asks: “CharOperation is technically internal but it seems generally useful enough to use elsewhere. I would like to see it made public.” Eclipse client asks: “CharOperation is technically internal but it seems generally useful enough to use elsewhere. I would like to see it made public.” Eclipse developer answers: “We could indeed surface it into a public package” Eclipse developer answers: “We could indeed surface it into a public package” Eclipse developer answers: “We could indeed surface it into a public package” 17
  18. Stable Documented Clients can use Unstable Undocumented Clientes should not

    use Internal Interfaces Public Interfaces Internal interfaces may become Public org.eclipse.internal.foo.Bar 2,155 145 (7%) org.eclipse.foo.Bar 18
  19. Internal interfaces may become Public 19

  20. Internal interfaces may become Public Which interfaces initially projected as

    internal should be promoted to public? 20
  21. Outline 1.Context 2.Problem 3.Study Design 4.Results 5.Final Remarks 21

  22. Research Questions • RQ1. Is there a relationship between internal

    interface usage and promotion? • RQ2. Can we predict that an internal interface will be promoted to a public one? • RQ3. Can we detect that an internal interface is a candidate to be promoted to a public one? 22
  23. Experiment Design Public x Internal interfaces Case studies 23

  24. Experiment Design Promoted x non-promoted internal interfaces 24

  25. Experiment Design Usage metrics Domestic metrics 25

  26. Outline 1.Context 2.Problem 3.Study Design 4.Results 5.Final Remarks 26

  27. RQ1 Is there a relationship between internal interface usage and

    promotion? 27
  28. RQ1. Is there a relationship between internal interface usage and

    promotion? 1. Separation of interfaces in promoted and non-promoted } } Non-promoted internal interfaces Promoted internal interfaces 2. Comparison of promoted and non-promoted internal interfaces (Mann-Whitney U test & Cliff’s Delta) 28
  29. RQ1. Is there a relationship between internal interface usage and

    promotion? 29
  30. RQ1. Is there a relationship between internal interface usage and

    promotion? 30
  31. RQ1. Is there a relationship between internal interface usage and

    promotion? Promoted and non-promoted internal interfaces present distinct distribution regarding their usage metrics 31
  32. RQ2 Can we predict that an internal interface will be

    promoted to a public one? 32
  33. RQ2. Can we predict that an internal interface will be

    promoted to a public one? Precision 50%–80%, recall 26%– 82%, AUC 74%–85% Random-forest classifier to predict promotion 33
  34. Random-forest classifier to predict promotion RQ2. Can we predict that

    an internal interface will be promoted to a public one? Precision 50%–80%, recall 26%– 82%, AUC 74%–85% Internal interface promotions can be predicted with high confidence 34
  35. Outline 1.Context 2.Problem 3.Study Design 4.Results 5.Final Remarks 35

  36. Final Remarks Internal interfaces are common practice: 21% (6,085 out

    of 28,503) Clients often use internal interfaces: 23.5% (2,277 out of 9,702 Eclipse clients) Internal interface promotions happen in real-world systems: 7% (195 out of 2,722) Promoted and non-promoted internal interfaces present distinct usage patterns Internal interface promotions can be predicted with high confidence 36
  37. When Should Internal Interfaces Be Promoted to Public? André Hora,

    Marco Tulio Valente, Romain Robbes, Nicolas Anquetil FSE 2016