JSelfDeception

In the Marketplace I stumbled across the plug-in JAutodoc. JAutodocs automatically adds Javadoc comments, e.g. if you have a private field numberOfQuestions it adds:

            /**
             * The number of questions.
             */
            private int numberOfQuestions;

This reminds me of an experience I made five years ago. We recognized that our software was hard to maintain especially by new employees like me. We considered that missing Javadoc comments was one of the problems. So we decided that all new public classes, methods, and fields must have Javadoc comments and that in existing files comments had to be added when the file is edited. JDT has a nice feature to show missing Javadocs as warnings.

(Painting by or found by James Vaughan)

Writing comments is annoying and so – surprise, surprise – few days later two developers independently had the great idea to generate Javadoc automatically. It is worth mentioning that one script was written in Visual Basic. From that time on we no longer wasted time because of missing comments. From that time on we wasted even more time reading stupid comments like “Gets the time”, “Sets the maybe defaulted value” (yes, there was a field maybeDefaulted but I never discovered its meaning), “Default Constructor”, and my favorite “Throws XYZExceptions when an error occurs”. Because Eclipse cannot distinguish between helpful und meaningless comments and show the latter as compiler warnings I used regular expressions and Checkstyle to identify these hidden problems. But that was just the beginning of arms race between people who want to solve problems and cheaters…

7 Responses to “JSelfDeception”

  1. Stefan Says:

    There’s anice book about Clean Code from Robert C. Martin: http://my.safaribooksonline.com/9780136083238
    In wich he states:
    “One of the more common motivations for writing comments is bad code. We write a module and we know it is confusing and disorganized. We know it’s a mess. So we say to ourselves, “Ooh, I’d better comment that!” No! You’d better clean it!

    Clear and expressive code with few comments is far superior to cluttered and complex code with lots of comments. Rather than spend your time writing the comments that explain the mess you’ve made, spend it cleaning that mess.”

  2. Philipp Kursawe Says:

    I agree that JDT should not warn on missing getter/setter method comments. It just clutters up the code and what it does should be pretty obvious. And if a certain setter expects certain input then you should comment it. But if all it does, is assigning a variable, then you better not comment it at all. For (non-primitive) getters it can be useful to state if and why the returned object can also be “null”.
    Maybe we should file a enhancement bug to finegrain the JavaDoc JDT warnings.
    “Missing Getter/Setter comments=[Error|Warning|Ignore]”

  3. howlger Says:

    @Stefan: Thanks for the link.

    @Philipp: Yeah, “null” is really annoying in Java.

    I agree with both of you: less is more. In OSGi-based projects an option “Only consider exported packages” would be nice to have. What do you think?

  4. Philipp Kursawe Says:

    Well, only documenting exported packages is certainly an option. But I do not know if JDT knows about that. However you should also document public internal classes (or even protected). But only to an extend where you describe the API contract and if its unclear what the class/method does. Getter/Setter should be documented very seldom.

  5. howlger Says:

    Sometimes you only have the choice to turn on a detector and get thousands of warnings or leave it off. I like to have a feature “Show me all missing Javadocs of the code I wrote or edited”. It’s very hard and error-prone to write proper Javadoc comments for code which you have not written.

  6. Maarten Meijer Says:

    When you have sensible names for variables and methods, you don’t need comments except to describe contract: return null or empty List, etc.
    So instead of checking for missing javadoc, it is probably better to create an incomprehensible or unclear method/variable name detector, than a missing javadoc detector.

  7. Bogdan Mocanu Says:

    I recently reviewed JAutoDoc, and I found it quite useless. One thing that I hoped was possible with it (and which I found to be very useful in practice) is to copy the comment of the fields to the getters and the setters.

    In most cases, when you write the code you document the fields of a class. Then, when you generate the getters and the setters, it would be great to have that comment copied for each of the 2 methods.

    However, from what I tested this is not possible with JAutoDoc. I tried tinkering with the Velocity templates that it supports, but to no avail.

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s


%d bloggers like this: