FIrst things first
2006-11-25 13:45:56 ewin
[Reply | View]
Where something is documented is not as important as what is documented - as long as it can be easily found.
Several J2SE class documentations are extremely bad. The worst are the ones where each method is documented in isolation, and only with a single sentence or two, but where the documentation not at all explains how all the methods are supposed to work together. Where the sequence of method calls is not clear and where the documentation is not capable of communication the idee the developer had when structuring a class in a particular way.
Also typically final static int constants are often individually explained in isolation and not even properly referenced in the method documentation where the constants are supposed to be used as arguments.
Equally "fun" are class documentations where the terminology is not explained. Particularly when the class developer worked from a very generic abstraction which doesn't map in a straight forward way to a real-world problem.
A class documentation might be formally complete if each public and protected slot is decorated with some sentence, but that documentation is useless as long as the information does not easily allow a developer to form a mental model of what is going on. Here several Java APIs fail miserable. It is maybe not a good idea to let the software developer also write the documentation.
Abother issue are code examples. I like to have code examples in the documentation. But not primarily the demonstration of "cool", esotheric features, but the plain vanilla usage of a class. The most common, obvious cases first. Then the common but not so obvious usage. And then we can talk about the rest.
Currently the code examples in the tutorials are even worse than the ones in the javadoc. The javadoc examples often only suffer from the problem mentioned in the previous example. However, the tutorial examples often demonstrate very bad coding practice. In order to keep an example short to many shortcuts are taken. That plus the fact that the tutorial examples are often extremely artificial, tool.
68.6% (455 Votes)
java.net RSS Feeds
