Question

Recently we planned to use checkstyle plug-in in our project. As a part of this exercise existing code has to be cleaned up to comply with checkstyle rules. We have found that close to 18K violations correspond to absence of javadoc comments in class files.

My question is, is there any plugin or tool which i can use to generate javadoc comments for the entire artifacts?
I had a look at JAutodoc , and I would
like to know whether there is anything better than this.

Answer 1

Your real code quality will go down by generating JavaDoc, even if the CheckStyle score goes up. Generated JavaDoc can only reflect what is already obvious from the code, it adds volume which decreases readability and it probably (depending on you tool) will not keep itself up to date, adding a maintenance burden and leading to inconsistencies after the code evolves.

Don’t let yourself be badgered into cluttering your code. The CheckStyle violations should be taken as hints, not absolute iron-clad rules. Adding sensible JavaDoc takes time and understanding of the code, you should make policy for creating it from now on in all new code, and add it in any existing code when it gets refactored.

BTW: you don’t have to JavaDoc everything. I personally don’t JavDoc default getters/setters, overrides or methods/fields with self-explanatory names (which I strive for). I always JavaDoc top level entities (interfaces, classes and enums) and put non-JavaDoc comments on blocks of code that do something complicated.