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
provides a method/service
blurp for the consumer
You may add further details to this simple graphical model, a few options given below (with increasing effort).
- You don’t explain this interface, as you know the corresponding source code is understandable or simple enough
- 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
- You explain return type and parameters of the call (assuming synchronous interaction)
- You additionally describe quality attributes that are required
or provided at this interface, i.e.:
Blurpcan process 10 requests per second, or
Blurpcan only be invoked sequentially.
Blurpby multiple clients will lead to runtime exceptions.