Tag Archives: Checkstyle

Automated Javadoc compliance checking with Eclipse and Checkstyle – how and why (NOT!?)

No doubt: Javadoc comments are important. With the support of an IDE providing hovers and views showing Javadocs of the third party code that I’m just using  (or the one that my half-genius co-worker wrote two weeks ago and that I will never understand/or did I code this weird stuff?) they boost my programming performance. Since it’s a boost, isn’t it a good idea to utilize a tool that checks the existence and compliance of Javadoc automatically while coding? This one is about a good intention gone bad:
Once, I was in a developer team and they were enthusiastic about Checkstyle validating the Javadoc compliance – quite similar to David Carver who blogged about Checkstyle JavaDoc Compliance Checking. Here are just two illustrative examples of comments that had been written by that team:

  • Useful Constructor-Javadocs
    /** Creates an instance of MyClass. */
    public MyClass() {
    }
    /** @param someParam */
    public MyClass(int someParam) {
    }
    
  • Copy-Paste-Javadocs
     /**
     * Adds two addends.
     *
     * @param s1 an addend
     * @param s2 another addend
     * @return the sum of s1 and s2.
     */
     public int subtract(int s1, int s2) {
       return s1 - s2;
     }
    

I’ve seen comments that were empty, nonsense, redundant (either within the comment or redundant to the code itself), obvious, outdated, wrong and/or annoying. I even found a lot of real gems: Comments that were really helpful and important.  The prob was that independent of the content, Checkstyle considered each of them “compliant”. I ended up not trusting any of them and analyzing  the sourcecode instead of reading untrustworthy Javadocs. Another thing was that those strict Javadoc compliance rules in combination with tough deadlines prevented me from writing clean code: Instead of separating reusable steps of an algorithm into methods with a clear scope (“extract method” is usually one of my favorites) , I inlined these fragments because otherwise I had to javadoc my extracted methods, i.e. I had to write Checkstyle-compliant Javadoc which might more confuse than help my co-workers. And to make matters worse, the error markers of the Eclipse Checkstyle-Plugin which covered other markers (e.g. breakpoints) and it showed hovers with Checkstyle-complaints regarding the Javadoc instead of hovers showing the actual Javadoc (remember: That is one feature that boosts my performance. In this project, it had an opposite effect.)

So here’s my point:

  • You must not force anyone to write superfluous Javadocs.  You may want to read what Adam Bien wrote about How to JavaDoc (efficient and maintainable) (don’t be scared, it’s only ~ 30 Lines).
  • You must not use an automated Javadoc compliance checker without a process that covers quality assurance of the Javadoc content. If you are strict, be strict!
    If your coding guidelines are strict regarding Javadoc compliance, use an automated compliance checker. Assuming that strict guidelines indicate a high level of quality requirements, I think that in this case, reviews are not such a bad idea at all!