-
Notifications
You must be signed in to change notification settings - Fork 9
API Design guidelines
API - code supposed to be implemented by qbit and called by client.
SPI - code supposed to be implemented by client and called by qbit.
qbit's API surface consist of packages:
- classes directly placed in
qbitpackage. The package defines entry points (Factories) for qbit functionality. - classes placed in package
qbit.apiand all it subpackages. These packages defines model of qbit intended to be used by qbit users - classes placed in package
qbit.spiand all it subpackages. These packages defines qbit extension points intended to be implemented by qbit users.
Everything in qbit and qbit.api packages should be defensed from subclassing by users. Everything in qbit.api packages should be defensed from direct instantiation by user. Everything in qbit.spi packaged should be designed for subclassing and/or implementation. Everything in all other packages should have internal access.
Keep API surface as small as possible.
Anything you publish can be used against you
Each API element should be backed by well-reasoned use case
- Anything you publish can be used against you
- Anything published should be maintained for all life span of qbit
Each API element should be either defensed from subclassing/implementation or designed for it.
API and SPI have different evolution modes. For API addition of methods is allowed, but removal is prohibited. For SPI the rules is reversed.
User should be able to find out how to perform given task without reading documentation.
It increases convenience and ease of use of qbit
It decreases annoyance of users
API classes, methods params and properties should be named and behave consistently with each other.
It increases convenience and ease of use of qbit and decreases annoyance of users