EnforcingProperUsage
From APIDesign
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?
Engineering solution
API designers are primarily engineers and thus it is no surprise they seek a technical solution. Using language encapsulation constructs like private or package private in Java to hide something from the eyes of API users works as it makes such elements (types or methods or fields) inaccessible (unless one resorts to reflection). Even languages without access modifiers allow ways to declare things privately - for example in JavaScript one can use scope to make objects inaccessible for external world.
Follow
