A public interface is the logical point at which independent software entities interact. The entities may interact with each other within a single computer, across a network, or across a variety of other topologies. It is important that public interfaces be stable and designed to support future changes, enhancements, and deprecation in order for the interaction to continue.

Guidance

• A project must provide additional documents that describe plans and procedures that can be used to evaluate the project’s compliance.
• Provide an architecture design document.
• Provide a coding standards document.
• Provide a software release plan document.
• Provide a document with a plan for deprecating obsolete interfaces.
• Create fully insulated classes.
• Insulate public interfaces from compile-time dependencies.

Best practices

• Present complete and coherent sets of concepts to the user.
• Design interfaces to be statically typed.
• Minimize the interface’s dependencies on other interfaces.
• Express interfaces in terms of application-level types.
• Use assertions only to aid development and integration.

Examples

• C++ interface

Use protocol classes to define public interfaces.

The characteristics of a protocol class are:

• It neither contains nor inherits from classes that contain member data, non-virtual functions, or private (or protected) members of any kind.
• It has a non-inline virtual destructor defined with an empty implementation.
• All member functions other than the destructor, including inherited functions, are declared pure virtual and left undefined.

Benefits

The benefits of using protocol classes include:

• Insulating applications from the external client
• Insulating changes that are internal to the interface
• Insulating changes to the public interface from changes to the implementation of the interface
• Insulation has costs, but these tend to be outweighed by the gains in interoperability and reusability.

Costs:

• Going through the implementation pointer
• Addition of one level of indirection per access
• Addition of the size of the implementation pointer per object to memory requirements