-
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)
-
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.
-
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.
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 Guideline: 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
work products.
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.
|
