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.

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