Joshua Bloch: Bumper-Sticker API Design
All programmers are API designers.
APIs can be among your greatest assets or liabilities.
Public APIs, like diamonds, are forever.
APIs should be easy to use and hard to misuse.
APIs should be self-documenting.
When designing an API, first gather requirements?with a healthy degree of skepticism.
Structure requirements as use-cases.
Early drafts of APIs should be short.
Code the use-cases against your API before you implement it.
Maintain the code for uses-cases as the API evolves.
Example code should be exemplary.
You can't please everyone so aim to displease everyone equally.
Expect API-design mistakes due to failures of imagination.
API design is not a solitary activity.
Avoid fixed limits on input sizes.
Names matter.
If it's hard to find good names, go back to the drawing board.
When in doubt, leave it out.
Keep APIs free of implementations details.
Be wary of overspecification.
Minimize mutability.
Documentation matters.
Consider the performance consequences of API design decisions, but don't warp an API to achieve performance gains.
When in Rome, do as the Romans do.
Minimize accessibility.
Subclass only if you can say with a straight face that every instance of the subclass is an instance of the superclass.
Design and document for inheritance or else prohibit it.
Don't make the client do anything the library could do.
