Paradoxes
From APIDesign
(Difference between revisions)
| Line 1: | Line 1: | ||
| + | Soon after publishing [[wikipedia:Kant|Kant]]'s [[wikipedia:Critique_of_Practical_Reason|Critique]], he realized that nobody is able to read it all and he released his [[wikipedia:Prolegomena_to_any_Future_Metaphysics|Prolegomena]] to summarize and re-explain in more understandable style the thoughts of his [[wikipedia:Critique_of_Practical_Reason|Critique]]. I'd like to my [[Paradoxes]] to do the same to [[TheAPIBook]] with the hope to attract wider audience to the topic of [[API]] design and convince part of them that is is worth to buy [[TheAPIBook]]. | ||
| + | |||
| + | |||
There is nothing unnatural on [[paradox]]es. 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 [[paradox]]es. | There is nothing unnatural on [[paradox]]es. 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 [[paradox]]es. | ||
| Line 17: | Line 20: | ||
* 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]]. | ||
| + | * Hurting yourself. [[Incremental deployment]] can hurt even author of the [[API]]. | ||
| + | * Freedom for everyone! The less freedom [[API]] users have, the better. | ||
* [[ClientAPI]] is different to [[ProviderAPI]]. Separate [[APIvsSPI]]. | * [[ClientAPI]] is different to [[ProviderAPI]]. Separate [[APIvsSPI]]. | ||
* [[Code Against Interfaces, Not Implementations|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. | ||
| + | * Review for beauty! No, use scientific [[netbeans:APIReviews|methods]]. | ||
| + | * Know it better! Who should know more? [[SuperVsInner]]? | ||
| + | * Bugs compromise compatibility! No, learn to provide [[AlternativeBehaviour]]. | ||
| + | * [[Modularity]] gives you flexibility. | ||
| + | * Reuse complicates use. TBD. | ||
| + | * Improve by remove. E.g. [[DiamondsVsStars|APIs are like stars]]. | ||
| + | * API design [[guidelines]]. | ||
| + | |||
| + | The above is your [[API]] design hand book reference. Deeper understanding of the topic can be obtained by reading [[TheAPIBook]]. Don't wait and get it [http://buy.apidesign.org here]! | ||
Revision as of 18:58, 19 September 2011
Soon after publishing Kant's Critique, he realized that nobody is able to read it all and he released his Prolegomena to summarize and re-explain in more understandable style the thoughts of his Critique. I'd like to my Paradoxes to do the same to TheAPIBook with the hope to attract wider audience to the topic of API design and convince part of them that is is worth to buy TheAPIBook.
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 is going to be 3 to 10 pages long and 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.
- Hurting yourself. Incremental deployment can hurt even author of the API.
- Freedom for everyone! The less freedom API users have, the better.
- ClientAPI is different to ProviderAPI. Separate APIvsSPI.
- Code Against Interfaces.
- Maintaining API is hard! No, it is not. Proper API Patch is cheap.
- Review for beauty! No, use scientific methods.
- Know it better! Who should know more? SuperVsInner?
- Bugs compromise compatibility! No, learn to provide AlternativeBehaviour.
- Modularity gives you flexibility.
- Reuse complicates use. TBD.
- Improve by remove. E.g. APIs are like stars.
- API design guidelines.
The above is your API design hand book reference. Deeper understanding of the topic can be obtained by reading TheAPIBook. Don't wait and get it here!
Follow
