Paradoxes
From APIDesign
(Difference between revisions)
(New page: There is nothing unnatural on paradoxes. Yet they attract human attention. They show where our expectation does not match reality. And that is exactly the place where we can learn some...) |
|||
| Line 17: | Line 17: | ||
* Where are the users? There is [[distributed development]]. | * Where are the users? There is [[distributed development]]. | ||
* Shield against change. Describe types of [[BackwardCompatibility]]. | * Shield against change. Describe types of [[BackwardCompatibility]]. | ||
| - | * [[ | + | * [[ClientAPI]] is different to [[ProviderAPI]]. Separate [[APIvsSPI]]. |
| - | * [[Code Against Interfaces]]. | + | * [[Code Against Interfaces, Not Implementations|Code Against Interfaces]]. |
* Maintaining API is hard! No, it is not. Proper [[API Patch]] is cheap. | * Maintaining API is hard! No, it is not. Proper [[API Patch]] is cheap. | ||
Revision as of 18:40, 19 September 2011
There is nothing unnatural on paradoxes. Yet they attract human attention. They show where our expectation does not match reality. And that is exactly the place where we can learn something new. That is why let's concentrate on paradoxes.
A clasification of an API paradox should contain:
- name
- description of the original expectation
- explanation how it works in reality of API design
- contra-opinion
- advice what to do
- warning what can go wrong, if you don't
- link to additional sources of informations (books, chapters, URLs)
The list of paradoxes should mention following ones:
- Who are your users? E.g. cluelessness.
- What is an API? Not just javadoc.
- API design is fun! No, it is not. It is more sustaining.
- API should be beautiful! Not at all, but it should be good and one should remember there are 3SidesToEveryAPI.
- Where are the users? There is distributed development.
- Shield against change. Describe types of BackwardCompatibility.
- ClientAPI is different to ProviderAPI. Separate APIvsSPI.
- Code Against Interfaces.
- Maintaining API is hard! No, it is not. Proper API Patch is cheap.
Follow
