Ever since I read Clean Code, I’ve been more aware of the uncleanliness of the code I write, and more importantly, the code I have to maintain. Although the book recommends against JavaDocs for variables, I find it necessary especially for anything that is considered to be API by the user. Yes, you should be able to tell what a method/function/class does by the name and its parameters, but it is always helpful as a consumer of the API to have a bit more detail.
On the various projects I work on at Eclipse and at eBay Open Source, I’ve started to use the very good CheckStyle project. CheckStyle has been been around for years, and to me is an under utilized piece of code. If used diligently, it can help catch a lot of issues from the lack of Header Licenses in source code files to missing JavaDoc or poorly written JavaDoc. Below is an example of the Eclipse CheckStyle Plugin run against the Turmeric Eclipse Plugin code for the Turmeric SOA project.
We have a CheckStyle configuration file that only enables the JavaDoc rules at this point. We found this to be our biggest pain point, and when you enable it, it catches a LOT of issues. You can of course tweak it but we left most to the default values, except we don’t require JavaDoc on private methods or variables. The nice thing about the Checkstyle plugin is that it makes use of the same Configuration files that the Maven Checkstyle Plugin uses, so we can guarantee the same results between the IDE and the Build.
The CheckStyle Plugin itself is licensed under one of the GNU licenses, so if your corporate policies don’t allow use of those, you can gain some of the benefits on JavaDoc style checking from within Eclipse itself.
By default most of the JavaDoc checks are disabled, but by enabling some of these especially for your code that is considered API, you can help your adopters out. Developers don’t like writing JavaDoc, but your users typically don’t like not having it either. With the functionality of most IDE’s running the actual JavaDoc report isn’t necessary, but having this extra Meta Data included in your code, can be very helpful for your adopters.