CODEWITHSUNDEEP
javafindbugscheckstylepmd
BestPractices
BestPractices

Reputation: 12876

How can I enforce documentation in Java code?

What options are there for enforcing that code is documented? I want something that will run as part of the build process e.g. a maven target that will check that code is documented (class level and method level) and report if any code is missing documentation.

Have looked at FindBugs, PMD, and CheckStyle, but they dont appear to offer this capability.

Upvotes: 4

Views: 1594

Answers (5)

RobV
RobV

Reputation: 28655

If using the Maven Javadoc plugin you can use the failOnWarnings parameter to enforce that any Javadoc warnings (which are issued for pretty much any missing Javadoc) will fail your build e.g.

<plugin>
  <groupId>org.apache.maven.plugins</groupId>
  <artifactId>maven-javadoc-plugin</artifactId>
  <configuration>
    <failOnWarnings>true</failOnWarnings>
  </configuration>
</plugin>

Note that other answers still apply, not all Javadoc is necessarily useful.

Another gotcha is that if you are using Lombok or a similar tool that auto-generates code that does not also auto-generate associated Javadoc then this will fail your builds (NB Lombok can add Javadoc to some, but not all, generated code). So if you want to use those kinds of tools you have to make a choice about just how strict you want to be about enforcing Javadoc comments.

Upvotes: 0

nrainer
nrainer

Reputation: 2623

Teamscale can check whether comments are missing. It can also assess the quality of the comments and reveal trivial as well as unrelated comments.

Disclaimer: I am a Teamscale developer.

Upvotes: 2

TheEwook
TheEwook

Reputation: 11117

Perhaps it is not exactly what you are looking for but you can use Sonar and call it when you compile the code. Sonar will provide with lots of information included checkstyle

Sonar is very easy to use and integrate with a maven project.

Doc: http://docs.sonarqube.org/display/SONAR/Installing+and+Configuring+Maven

Upvotes: 1

Steven Mai
Steven Mai

Reputation: 63

A while ago there was this doclet from Sun called DocCheck. Creates a report from the javadoc. Don't know if its still available..

Do a google search.

Ok, google search... works with version 1.2, 1.3 and 1.4. Its experimental and appears to be inactive. Is it worth using now? I don't know. That's something for you to decide.

javadoc doccheck download http://192.9.162.55/j2se/javadoc/doccheck/index.html

Upvotes: 0

barfuin
barfuin

Reputation: 17494

Well, I hate to tell you this, but useful documentation cannot be enforced using tools.

Checkstyle can check if Javadoc is present, but it cannot check that the Javadoc contains anything other then @param pMyParam the myParam and other meaningless junk. Even if you let some tool check the contents of the docs, this would produce loads of false positives and would lead to simple, but useful comments to be inflated only to please the checking tool. After some time, the developers will learn to filter out Javadocs when reading code like we filter out ads when reading a web page. So, all tooling will gain you nothing if the developers do not want to write good and helpful docs.

To say it with the words of Antoine de Saint-Exupéry: If you want to build a ship, don't drum up people together to collect wood and don't assign them tasks and work, but rather teach them to long for the endless immensity of the sea.

My recommendation is: Use checkstyle to check for the very basics, such as the fact that each class has at least a type comment, and that interfaces document their methods as well. Then, educate the developers where necessary on what makes a meaningful and useful documentation, and make it clear that in the eyes of the development lead, good quality code has good quality docs. Javadocs can be very good even if certain methods are not documented at all. The checking can then only be done by manual inspection, e.g. by peer reviews or some kind of formalized step in the quality control process.

Just my two cents.

Upvotes: 3

Related Questions