Alexander Zuban’s Homepage

Here is some my thought about java doc.

Personally me sceptical about putting lots of javadoc and examples of usage in javadoc.

The reasons I say so:

• Due to human nature nobody in the project will read them.
• Most of projects are business oriented, and not used as a public library, so javadoc is not such critical, so your code will not be used as a black box by many developers all over the world
• I believe that the code should be the primary documentation because it has all the details, when developers looking into code they are getting better understanding of the things and can change them in more desired way.
• Support of javadocs will add additional time overhead and will make refactoring task more complex (or after the code refactoring javadoc will be dirty).
• In 90% cases, javadocs created by developer not give more information then method signature, e.g. javadoc for the function getFile will be “This method return the file”.
• For the distributed team specific (people who working 10-15 hours per week) spend 1-2 hours to put javadocs looks too prodigally as for me.

So I am follower of the idea, that code should be understandable in the same level that javadoc and instead of putting code example into the comments, it is better to create a JUnit test.

Some examples of the comments-javadocs I saw recently:


/**
* Construct object instance with default parameters.
*/
public SomeClass(){
...
}



/**
* Registers new listener.
*
* @param l
* the listener to register.
*/
public void addChangeListener(ChangeListener l) {
...
}


// Start transaction.
session.beginTransaction();
....
// Commit all changes.
session.commit();


Well, as for me such comments just add additional lines to code and make it harder to read(good that eclipse has folding feature for the method javadoc).

So again, javadoc is very useful for open source projects, but I am skeptical about using them in business related projects, and developers can’t write good javadoc documentation.