The document discusses the promotion of internal interfaces to public ones in software systems, highlighting that 21% of clients use internal interfaces and that promotions do occur in real-world systems. It outlines best practices for API development, emphasizes the need for stable public interfaces, and presents research questions regarding the predictability of internal interfaces becoming public. The study finds distinct usage patterns between promoted and non-promoted internal interfaces, indicating that promotions can be accurately predicted.

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