Is there a way to validate the presence of Javadoc and/or inline code comments?

Question

We are trying to put quality code processes in place for a large project I am working on. Right now a lot of developers are not putting in Javadoc or in-line code comments into their code. Ok right now. But it will severely hurt us in the very near future. We are using Maven 2.0.9 as our build tool, as well as Hudson for Continuous Integration. We are using Subversion as our source versioning tool/code repository, Rational Application Developer and Rational Softare Architect (essentially Eclipse) 7.5.1 as our IDE's, and then Subclipse as our Eclipse plug-in to connect to SVN.

Is there a plug-in or a way to validate that a developer put in Javadoc and/or in-line code comments in order to allow a commit to SVN? This isn't intended to be a substitute for good code reviews, but merely a help to make sure that developers are reminded to add this documentation before committing. We are still intending on conducting code reviews that would also review documentation.

Has anyone found any plug-ins for something like this? Any links? Any ideas?

Answer 1

Definitely check out the Checkstyle Eclipse plug-in. It supports many style checks, which can be configured and I think I heard of Hudson plug-in. It checks among others also for the presence of comments.

Answer 2

Maybe doxygen has more configuration possibilities than javadoc? It should be compatible with existing javadoc comments, so it might be worth a try to run it on your code base.

It is possible to make a doxygen build fail if there are undocumented things in the code. However doxygen is so slow-running that it is questionable if it is good to have it as a svn checkin hook.

Answer 3

You need a tool that can scan the source text, and determine if the javadocs are in place. Ideally, such a tool would verify that the javadocs that you want are in place, that they mention the current configuration of the software (nothing worse than a Javadoc comment about a nonexistent parameter).

Ideally, such a tool would insert the skeleton of missing javadocs along with text indicating it wasn't filled in properly.

An ideal tool to do this is a program transformation engine, that can read the source code, located the comments (or thier absence), check the comments for accuracy to the extent they can be determined form the code (properly documented types, etc.) and insert the skeletons as needed.

This can be accomplished using the DMS Software Reengineering Toolkit, which has a full-featured Java parser, builds ASTs [with comments retained] and symbol tables. You'd need custom code to walk over the trees and do the checking/comment insertion, but this should be pretty straightforward.

Answer 4

I recently started a open source JavaDoc checking utility: OpenJavaDocCheck. The project is fairly young, but some features are:

• XHTML+RDFa output (or just XML, so that you can use XSLT to create whatever)
• extensible (to test for project specific JavaDoc patterns, such as custom tags)

I am not sure if you can easily hook it into a svn precommit hook filter, but integration into Maven could be done with an Ant call like this (taken from this demo.xml build script):

<target name="demo">
  <antcall target="ojdcheck-project">
    <param name="project" value="com.github.ojdcheck"/>
    <param name="path" value="com.github.ojdcheck/src"/>
  </antcall>
</target>

<target name="ojdcheck-project">
  <javadoc private="false" public="true">
    <doclet name="com.github.ojdcheck.OpenJavaDocCheck"
            path="ojdcheck.jar:ojdcheck-jazzy.jar">
      <param name="-xhtml"/>
      <param name="-file"
            value="../ojdcheck-ghpages/${project}.html"/>
      <param name="-tests"
            value="com.github.ojdcheck.jazzy.SpellCheckerTest"/>
    </doclet>
    <sourcepath>
      <pathelement path="${path}"/>
    </sourcepath>
  </javadoc>
</target>

The split up into two target is, of course, not needed, but makes it easier for me to run OpenJavaDocCheck on multiple projects.