Public interface

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.

Design

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

References

*Various methodologies, such as refactoring, support the determination of interfaces. Refactoring generally applies to the entire software implementation, but is especially helpful in properly flushing out interfaces.
*There are other approaches defined through the pattern community. You can obtain these methodologies from the pattern community at [http://hillside.net/patterns/] .
*See "Java Design: Building Better Apps & Applets" for a good introductory methodology that also applies to the C/C++ community.