Guidelines: Interface
Topics
Naming
Interfaces 
- Name the interface to reflect the role it plays in the system.
- The name should be short, 1-2 words.
- Don't include the word "interface" in the name; it is implied by the type of model element (e.g. interface)
Describing
Interfaces
- The description should convey the responsibilities of the interface.
- The description should be several sentences long, up to a short paragraph.
- The description should not simply restate the name of the interface, it should illuminate the role the interface plays in the system.
Defining
Operations
- Operation names should reflect the result of the operation.
- When an operation sets or gets information, including set or get in the name of the operation is redundant. Give the operation the same name as the property of the model element that is being set or retrieved. An operation thusly named, without parameters, retrieves the property; an operation thusly named with a parameter sets the property.
Example
name() returns the name of the object; name(aString) sets the name of the object to aString.
- The description of the operation should describe what the operation does, including any key algorithms, and what value it returns.
- Name the parameters of the operation to indicate what information is being passed to the operation.
- Identify the type of the parameter.
Documenting
Interfaces
The behavior defined by the Interface is specified as a set of Operations. Additional information may need to be conveyed:
- How the operations are used, and the order in which they are performed (illustrated by example sequence diagrams).
- The possible externally-observable states a model element which realizes the interface may be in (illustrated by a state machine, see Guidelines: Statechart Diagram).
- Test plans and scripts which test the behavior of any model element which realizes the interface.
In order to group and manage this information, a package should be created to contain the interface and all related artifacts.
Hints and Tips
Every interface represents a 'seam' in the system: a place at which the system can be "pulled apart" and rebuilt or redesigned. Interfaces represent the separation of specification from design or implementation. Well structured interfaces:
- are simple yet complete, providing all necessary operations, yet sufficient to specify a single service
- are understandable, providing sufficient information to both use and realize the interface without having to examine an existing usage or implementation
- are approachable, providing information to guide the user to its key properties without being overwhelmed by the details of the operations
When you draw an interface,
- use the "lollipop" notation whenever you need to simply specify the presence of a seam in the system. Most often, you'll need this for subsystems but not classes.
- Use the expanded "class" notation when you need to present the details of service itself. Most often, you'll need this for specifying the services offered by a package or subsystem.
