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.

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