Teamwork
From APIDesign
Contents |
Have You Ever Wondered...?
There is a common wisdom among programmers saying that design cannot be done by committee. However how can we design bigger and bigger systems without designing in teams? Does not that hurt consistency? Yes, partially. Most people seem to be able to keep design consistency when they work alone, however software projects of today and of the future are designed by teams. Keeping consistency in such environment is much harder, but it is possible. Chapter 16 describes what aspects need to be verified and checked, and introduces the APIReview process which is capable of doing so.
Convincing Developers to Document Their API
The Teamwork chapter also contains section called Convincing Developers to Document Their API. One note there nit picks on GeertjanWielenga for being afraid to modify Javadoc. After many weeks of convincing him, I am happy to report success! As Geertjan just disclosed on his blog, he finally changed javadoc to point to one of his tutorials. Perfect! Geertjan confesses that the final reason that forced him to fulfil his promise lies in the fact that I used a tape recorder and recorded him swearing to do it. Maybe, this may be the final decision contributor, but not the most important one! The most important moment happened a month ago when, by an accident, I disclosed to Geertjan that Javadoc is just an HTML text. Before that Geertjan probably thought that the Javadoc is something complicated and was afraid of it. When Geerjan realized that it is just another version of HTML, his fear started to disappear. That was the breakpoint. Then it took just one month and one pub visit to remove it completely. Geertjan, I am glad, you managed to make such a significant step on your road to be API guru!
--JaroslavTulach 16:05, 17 July 2008 (UTC)
Accepting Patches
The Teamwork chapter claims that maintaining an API is no harder than maintaining the same code without API. The essential precondition in such claim is that there are no bugs in already released API. The details can be found in the Chapter 16, here is description of related adventures.
Paying More Attention to Your Issues
Recently I've been given the privilege to become default owner of many NetBeans platform APIs including openide.nodes, openide.explorer, openide.loaders, openide.filesystems, and others (I deserve that, I've created them back in 1997). However I've also received 200 new bugs. This does not make me feel comfortable. In such huge amount of issues, it is almost impossible to realize that some new arrived. It is impossible to really deal with the issues. At best they lay around unnoticed. I don't think this is good destiny for a bug report, and thus I decided to reduce their number significantly.
I went through the issues and eliminated those which did not seem important. Of course I fixed trivial NullPointerException, etc. On the other hand, reports about improper behavior without an automated test had to be closed. Enhancements without patches too. You may find this impolite, but this is the only way to scale the development. If you really want an enhancement to be implemented, we have API Review process that allows you to contribute.
The number of API issues will get down to manageable level in a few weeks. When we get there, it will be possible to pay more attention to newly reported inquiries and deal with them in more polite way. Issues shall not be left laying around for few releases unnoticed anymore. At the end we shall all benefit from the radical elimination of the number of open issues in NetBeans APIs.
No Bugs in Already Released APIs
The above attitude can probably only be applied to APIs (although similar attempts may be observed in Agile movement too). We can expect those reporting nontrivial issues against API to have some level of engagement (e.g. be able to write a code and/or test). However if you provide end user functionality you may need to treat your users differently.
In an API (where BackwardCompatibility is the primary concern), there are either trivial bugs (exceptions at unexpected places) or there are features. After a release (due to the BackwardCompatibility implications) every bug (usually a report that something is not nice, beautiful or rationalistic enough) turns into a feature.
As such reproducing and fixing a bug in an API requires different attitude. Encouraging community to seek for bugs in an API by providing patches to tests demonstrating wrong behavior is the best way to make the API really usable. On the other hand, the maintainer needs to be careful to not accept bad patches. The chapter 16 describes strategies to evaluate quality of submitted patches and separate the perils from dust. But the rules are simple. An API bug report has to be good:
- it has to be easy to verify the problem is there - the best way to do it is to have an automated test that can just be executed and the misbehavior reveals itself automatically
- when the fix is applied (and subsequent changes are made in future) one can easily verify that the original intentions are still valid - again automatic test is your best friend
- the change needs to be cool - well, API writers are glad to accept patches, if they are good (notice the self reference in the definition).
The above shows why maintaining of an API may be simpler than maintaining similar functionality without an API. There is just one requirement: the API owner needs to be ready to accept the good patches. It needs to encourage the community to write high quality API Patches. Dear NetBeans API users, this wiki page is my attempt to provide such encouragement. I am looking forward your patches for openide.explorer, openide.nodes, openide.loaders, etc.
Accepting Unacceptable
There are cases when API owners don't want to accept some contribution. This is unfortunate, but it may happen. Then please use this little coding trick, called code injection, to balance the need for extensibility while lowering overall Cost of Ownership. While using API CodeInjection it is basically possible to donate API Patch to any API.
<comments/>
Parallel Project Integration
Preventing mistakes as early as possible is a prerequisition for effective work in team. Read how we used Mercurial to isolate each other from mistakes that we, the clueless programmers, do daily.
