Describe or specify internal interfaces with minimal effort: You can find arbitrary interface details in source code, if you need to.

Be especially careful with graphical interface descriptions (like UML).

Take a look at the following diagram, where Blurp provides a method/service blurp for the consumer FooBar.

simple interface description diagram

You may add further details to this simple graphical model, a few options given below (with increasing effort).

  1. You don’t explain this interface, as you know the corresponding source code is understandable or simple enough
  2. You explain the semantics of using this interface, i.e. business processes handled by the interface, business or technical consequences of this interface, potential side-effects
  3. You explain return type and parameters of the call (assuming synchronous interaction)
  4. You additionally describe quality attributes that are required or provided at this interface, i.e.:
    • Blurp can process 10 requests per second, or
    • Blurp can only be invoked sequentially.
    • calling Blurp by multiple clients will lead to runtime exceptions.

See also