Public interface

From Wikipedia, the free encyclopedia

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.

image:Public_interface.gif

Contents

[edit] Design

[edit] 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.

[edit] 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.

[edit] 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

[edit] 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 [1].
  • See "Java Design: Building Better Apps & Applets" for a good introductory methodology that also applies to the C/C++ community.