Today I watched the infoq.com presentation on "How to design a good API & Why it matters" by Joshua Bloch. Among the many good pratices which he talked about, one which I could relate most has to do with API documentation. He explains that one must document every aspect of API so that API user has complete clarity on what to expect from API. Otherwise, user will either (wrongly) guess the functionality or look into implementation to find out the behaviour, and at which point the API no more remains implemenation independent, because the API user would have programmed to implementation. And if you change the implemenation tomorrow, you will break the code.
Now, the reason why I say I could relate to it more was due to my recent experience with working on log4j. Log4j is a small framework for logging in Java, but incidently their documentation is something which seem to have got least attention. I had confusion about how they have implemented the some of the filters, namely LevelRangeFilter and LevelMatchFilter. And I wanted more clarity on how the acceptOnMatch value behaved. I just looked into their implementation of the two classes, and found that both of them behave differently when they need to return the decision on whether filter match was successful or not. One of them returns NEUTRAL if acceptOnMatch is not set to true, and another returns DENY. NEUTRAL decision allows rest of the filters from filter chain to be evaluated.
I realized that most of the filters I needed for my app were supposed to behave with the rule "DENY as early as possible, ACCEPT as late as possible". Hence, I implemented my own versions of LevelMatchFilter and LevelRangeFilter.
Documentation seems to be most difficult aspect especially because most progammers like to shy away from it. However, its importance does not diminish in any way, and hence, we should try to make honest attempt in documenting our APIs. Equally important aspect of an API design is to have consistency in implementation of variants of a concepts, such as filters in log4j.