EnforcingProperUsage
From APIDesign
(→Striving for Clarity) |
(→Trying to Hack) |
||
| Line 7: | Line 7: | ||
== Trying to Hack == | == Trying to Hack == | ||
| - | + | On the other hand, when striving for [[clarity]], it often happens that the [[API]] is more restrictive than its users might want it to be. What the users do then? They hack! | |
| + | |||
| + | Of course [[good]] [[API]] users shouldn't hack - they should contribute! As described in [[Chapter 16]] ([[Teamwork]]), proper [[API]] designing project should have guidelines for accepting patches (like [[netbeans:APIReviews]]) and should be ready to accept contributions from its users. | ||
| + | |||
| + | However it is way easier to hack than to contribute an [[API]] patch! Some projects (for example [[OpenJDK]] comes to my mind) are hostile to random community contributions and getting simple patch in is almost impossible (as my own experience with small enhancements to {{JDK|java/lang/ref|ReferenceQueue}} and {{JDK|java/util|ServiceLoader}} shows), however even project open to contribution like [[NetBeans]] require one to justify the change, write a test, document it and make sure it is [[BackwardCompatible]]. That is still quite a lot of work. | ||
| + | |||
| + | No wonder users resolve to hacking. How can [[API]] designers prevent that? | ||
== Preventing the Hacking == | == Preventing the Hacking == | ||
Revision as of 07:24, 14 June 2015
API design is about communication between the API designer and its API users. Good API can be recognized by quality of the communication between the designer and the users. Does the vision of proper API usage (in header of the designer) recreates properly in heads of the users? If not, your API is probably suffering from a poor clarity. Do you users hack around your API - e.g. use things clearly stated as not being part of the API? Can you prevent them to do so? Those are question this essay is about to analyze.
Contents |
Striving for Clarity
If an API reaches clarity - e.g. everything in the API has a single meaning - then there is no reason to enforce anything - users either use something (method, class) or not. However, as everything (method, class) in the API has a single meaning, if they use it, they have to (or at least chances are very high) use it correctly. That is the reason why it is important to follow the API design patterns for Clarity and focus on ClarityOfAccessModifiers, ClarityOfTypes and separate API from a service provider interfaces.
Trying to Hack
On the other hand, when striving for clarity, it often happens that the API is more restrictive than its users might want it to be. What the users do then? They hack!
Of course good API users shouldn't hack - they should contribute! As described in Chapter 16 (Teamwork), proper API designing project should have guidelines for accepting patches (like netbeans:APIReviews) and should be ready to accept contributions from its users.
However it is way easier to hack than to contribute an API patch! Some projects (for example OpenJDK comes to my mind) are hostile to random community contributions and getting simple patch in is almost impossible (as my own experience with small enhancements to ReferenceQueue and ServiceLoader shows), however even project open to contribution like NetBeans require one to justify the change, write a test, document it and make sure it is BackwardCompatible. That is still quite a lot of work.
No wonder users resolve to hacking. How can API designers prevent that?
Follow
