At 42 we're using Checkstyle to enforce that every public method that is not a getter and setter has a JavaDoc comment.

The rationale behind this is that we want to deliver high quality, highly maintainable code and prove it using the reports that Maven and our Continuous Integration environment produces.

However, our developers didn't see the point of writing JavaDoc for all these methods. And so, we'd entered the..

The Great JavaDoc War

26-07-2009, By E.Hooijmeijer

The initial complaints were based on the (rather good) 'Clean Code' book by Robert C. Martin which says that a good method name should not need any additional documentation. Which is of course true, but in reality this means that everything the method touches must have the same elegance, which does not happen a lot (Think J2EE, Web Frameworks etc). But try explaining that to somebody just read the Clean Code book :)

Anyway, discussions on principle were soon over as real work commenced. Developers are smart, but also lazy, so they quickly configured their IDE's to generate JavaDoc based on the method and class signatures. 'Represents a ...' and 'Does a ...'. I'm sure you know these kind of pointless comments.

So now we had an automated tool that checked automatically generated comments. It was clear that this situation could not go on much longer as the code became more and more polluted with these 'comments'. It was time for some serious discussion.

So, why should every non trivial public method have a JavaDoc comment?

• Opportunism - they can (and will) be used outside the scope they are defined in.
• Reuse - the purpose, behavior, pre and post conditions, parameters or thread safety, may not be obvious from its signature.
• Maintenance - not everybody will have in depth knowledge of the code, but still need to be able to fix things.

And why do I want to have this automatically checked?

• Awareness - everybody can see how (well) documented the code is.
• Laziness - developers need a gentle reminder that they do need to write JavaDoc.
• Overconfidence - developers tend to overestimate the capacities of their successors.

The trouble with this definition is the word trivial and how you can explain it to Checkstyle. Currently the only way to do this by stating that all public methods must have JavaDoc, except getters and setters.

But there are much more methods that are so simple that they can be understood by their name alone. Also, we exclude all non public methods from having mandatory JavaDoc but they may actually require some.

They only way out of this was to create a check that somehow could determine the complexity of the method and then decide if it should have JavaDoc or not.

The good news that that checks and algorithms to determine complexity already exist in Checkstyle. However checks cannot be configured to have a dependency on each other. So the only way forward was to create a check of our own. Which I did :)