Andrew trained as a biologist before transmuting into a software engineer. He's been coding in Java since 1997, and has done a bit of scientific software, a bit of mobile gaming and lots of enterprise software. He's particularly interested in humane and sustainable development. Professionally, that means code maintainability and agile methods. Outside the professional sphere: permaculture, gardening, cooking, green transport and raising children (not by order of importance). He also loves ensemble singing, but that’s on hold for now. Andrew is a DZone MVB and is not an employee of DZone and has posted 9 posts at DZone. You can read more from them at their website. View Full User Profile

Autogenerated Comments Rant

11.12.2010
| 4180 views |
  • submit to reddit

Let me clear up potential confusion right at the start. My rant is not auto-generated. Auto-generation of comments is its object. What I have to say about this abomination can be summed up in six words: why, why, why, why, and why? Oh, and a seventh:

WHY?

I am talking about those handy little JavaDoc comments that well-known IDEs thoughtfully generate for you along with JavaBean-style property accessors, new classes, and indeed anytime a "wizard" (wash my mouth out with soap and water) gets its hands on your project. Here’s a particularly heinous example I found at work lately. Pseudonyms have been used.

package bet3.gov.it.abc;

// import statements

/**
* <p>
* Coordonnée physique
* </p>
* <p>
* <b>© Copyright 2010 B3IT - Betelgeuse 3 World Government.</b>
* </p>
* <p>
* <b>Société</b> : B3IT - Betelgeuse 3 World Government {@link <a href="http://it.gov.bet3"> B3IT - Betelgeuse 3 World Government </a>}
* </p>
* <p>
* <b>Projet</b> : abc-service
* </p>
* <p>
* <b>Historique des modifications</b> : <br>
* <br>
* 4 janv. 2010 - création du fichier. <br>
* <!-- date - {@link <a href="">lien vers JIRA</a>} --> <br>
* </p>
*
* @author bloggsj
*/
public class Coordonnee implements Serializable {

/** La constante serialVersionUID. */
private static final long serialVersionUID = -6370799192505622281L;

/** Le/la email. */
private String email;

/** Le/la fax. */
private String fax;

/** Le/la id. */
private long id;

/**
* Permet d'obtenir la valeur de "email".
*
* @return la valeur de "email"
*/
public String getEmail() {
return email;
}

/**
* Permet d'obtenir la valeur de "fax".
*
* @return la valeur de "fax"
*/
public String getFax() {
return fax;
}

/**
* Permet d'obtenir la valeur de "id".
*
* @return la valeur de "id"
*/
public long getId() {
return id;
}

/**
* Affecte à l'objet la valeur "email".
*
* @param email la nouvelle valeur de "email"
*/
public void setEmail(String email) {
this.email = email;
}

/**
* Affecte à l'objet la valeur "fax".
*
* @param fax la nouvelle valeur de "fax"
*/
public void setFax(String fax) {
this.fax = fax;
}

/**
* Affecte à l'objet la valeur "id".
*
* @param id la nouvelle valeur de "id"
*/
public void setId(long id) {
this.id = id;
}

// umpteen other properties left off for brevity - I think you got the picture anyway

}

The purpose of a comment is to help understand the code. It does so by providing information that is either missing or difficult to deduce from the code.

Let us not forget that a comment has a cost. It adds bulk to source code, hindering the reader. It adds extra text to modify in the event of maintenance (though refactoring tools may help). It must justify that cost by the value it adds.

A comment that simply repeats information in the method's signature cannot possibly have any added value. Most IDEs already advertise a method's signature, through syntax highlighting, autocomplete and tooltips, more prominently than they do its accompanying comment.

Now, I know that you can switch off comment auto-generation and get comment-free generation of accessor methods. But the auto-generation is switched on by default, and most developers don't switch it off. This brings us to my opening question: why? Why do IDE makers think there is any point in auto-generating comments at all? Why on earth do they think it should be switched on by default? And why, why, why don't most developers switch it off? What can they possibly have between their ears, to see any use in a source file three-quarters full of completely valueless noise? Java is verbose enough already. There's no need to go adding yet more unnecessary guff.

(Oh, by the way - the code quoted above is particularly heinous because it doesn't use the IDE's automatic comment generation. Someone actually went to the trouble of configuring their own pointless comment generator.)
Published at DZone with permission of Andrew Spencer, author and DZone MVB.

(Note: Opinions expressed in this article and its replies are the opinions of their respective authors and not those of DZone, Inc.)

Comments

James Sugrue replied on Fri, 2010/11/12 - 6:49am

I totally agree with you - auto generated comments will typically add no value to your code. Much better to have meaningful variable/method names, rather than that type of documentation. 

James

Carlos Hoces replied on Fri, 2010/11/12 - 8:51am

I don't see anything wrong with an IDE helping to save typing for usual tasks.

All public, well constructed API must have Javadocs, so if the IDE helps by building the skeleton for them, I won't complain.

What an IDE cannot do is to write meaninful Javadocs for any code: that's a programmer's task. But once you have the skeleton ready, it saves time to fill it with the appropiate information. Apart from the fact it is much easier to remember you have to make the Javadocs when you see the skeletons, than when they're missing.

Verbosity is a matter of an endless discussion: I prefer a verbose code I can easily understand, to an stripped-down code, so criptic I might need a "translator" to figure out what the hell it does! ;-)

Adam Davis replied on Fri, 2010/11/12 - 10:52am

In my opinion, comments can be good, bad, or neither. These comments are neither. Although you can certainly argue that the code would be easier to read without the comments (because there's less to read), these comments aren't actively misleading. It could be worse -- the generated code could contain "TODO" comments which were never removed by the programmer ("Auto-generated method stub", "Auto-generated catch block", etc). Once you get a few dozen of those in a codebase, it gets hard to tell which "TODO" comments actually refer to issues which still need to be addressed. It's pretty alarming to start working on an existing project with hundreds of "TODO" comments without knowing which of them you actually need to worry about.

Mladen Girazovski replied on Mon, 2010/11/15 - 3:48am

What annoys me even more than useless JavaDocs are JavaDoc Comments that are NOT in english, same with the Classnames.

As soon as people use any other language for Javaclasses or javaDocs than english, they are abusing at least 2 languages.

Java syntax is a small subset of the  english langauge, as with most programming languages. There is no benefit in adding another language to that by using non-english for classes and/or comments.

Cosmin Mutu replied on Mon, 2010/11/15 - 4:08am

totally agree with Mladen ... but hey, he`s french :) you should had seen this coming ... they DON`T speak ENGLISH :) ... it`s not that they couldn`t .. it just that they won`t :) ... if you think about it, that`s why he`s so upsed with the auto generated comments ... those are in english :))

Andrew Spencer replied on Mon, 2010/11/15 - 5:44am

@everybody Thanks for all the comments, including -- no, especially -- the ones I don't agree with. :) You made me realise there's quite a lot that can be said about the subject.

@Carlos Hoces "All public, well constructed API must have Javadocs"
I've seen this assertion elsewhere -- including the Sonar rules at the organisation I work in -- and I'd be interested to read a justification for it. I don't adhere to it, though that partly depends on the definition of "public". (The keyword "public" doesn't itself say much about how widely disseminated the code will be.) Here's why.

In the example I quoted, we're talking about a transfer object which is only shared between the service and web layers of the same project. It contains only Javabean accessor methods, no business rules, and the only words in the method names, besides "get" and "set", are application-wide business terms. And while those terms do need defining, it's not clear that this class is the best place to do so (admittedly that depends on context, and in some contexts it might be the right place). So, in this example I don't believe that there's a clear need to provide more than what the method names have already given us.

For code intended to be re-used outside the scope of its own project, I agree that you should usually expect to see some documentation in the Javadoc comments. Even in this case, however, I maintain that a comment that only repeats information coming from the method signature adds no value, and something that adds no value should not be in your code. So: either you need more than the method signature, and you put what's needed in the API comment, or you don't need anything more, and a comment is not justified.

Btw I totally agree with you about preferring verbose to concise code.

@Adam Davis: from an accuracy point of view, you're right, and if the code maintainer uses the IDE's refactoring tool, they'll probably stay accurate even through method renaming. I'm arguing that they're bad because of the processor cycles that they waste in the developer's brain, making the effort to ignore them.

Certainly, this is much less bad than actively misleading information, and if these pointless comments only took up 10% or so of the source code, I wouldn't mind so much. But in the example I gave, there are 6 lines of genuine information (package statement, four properties, closing brace), 18 lines of accessor method (arguably redundant, but we can all agree that Java does require them, unless we use Lombok), ten lines of whitespace (very necessary IMO), for a total of 34 lines that are pulling their weight. The overall source file is 94 lines, if we ignore the sarcastic little comment I added at the bottom, so that's... wait for it... sixty four percent of noise.

OK, I'm being slightly unfair. The class comment does mention that it is not just any Coordonnee, but a coordonnée physique (good luck for guessing what that means), but in any case, it's well over half junk, which is far too much. And to make matters worse, the junk is distributed towards the top of the file.

@Mladen Girazovski and Cosmin Mutu: the language question deserves a discussion all to itself. I'm currently working for public-sector administration that governs an entirely monolingual area and that, in addition, is linguistically self-determining (so I don't have to worry that a higher authority might require it to produce translations of all administrative business into Vulcan, for instance). All development is done on-site or by French-speaking partners.

In these circumstances, I give precedence to the practice of using business vocabulary, which is in French, for all business elements in the code, but sticking to English for purely technical elements. This makes for a bastard mixture of technical words like "set", "get", "forward", with business terms like "Personne", "Adresse", "Medecin". I've tried the alternative, which is to use English translations of all the business terms referred to in the code, but this is far more problematic... I can explain in detail if you would like, but I don't want to bore anyone. :-)

If you were working with a multi-lingual team, or for a multi-lingual organisation, I agree that the code would have to be in English; but in that case, the business vocabulary would probably be in English already.

Btw I'm English myself, although I do worry that living in France might have polluted my English writing style.

Carlos Hoces replied on Mon, 2010/11/15 - 8:34am

When you use code written by someone else, even your own code written long ago, you have two choices to understand what that piece of code does: you digg into the source (if it's available), or you rely on the Javadocs.

This only applies to public API, that is: public methods. Sure there's no need to publish in Javadocs private variables, constants and methods. I usually write classes with more of a thousand lines, having no public API at all. But any class having externally accesible methods, should have some sort of meaninful documentation, easily available w/o resorting to read the code itself.

I need to know what the method does, which value it returns, if any, what's the meaning for each parameter, and which exceptions it throws, if any. Also, if returns any null value, under which conditions might it happen. That's usual Javadocs contents.

I use NetBeans, and I find quite useful to see the Javadocs popping-up, once I want to know which methods would be appropriate to the logic I'm designing.

Even more, when you work within a team, you must be sure the remaining members would understand the basis of your own code, w/o forcing them to read over and over the source itself.

These could be some reasons to justify "All public, well constructed API must have Javadocs" sentence.

Andrew Spencer replied on Mon, 2010/11/15 - 10:44am in response to: Carlos Hoces

I prefer to dig into the source, when I need to understand some code: it's more reliable. That's why I place a relatively low importance on comments, and more importantly, a very high importance on intention-revealing code. The only time I look at the Javadoc before the source code is with published (i.e. library) code. Not for "public" methods that are, in reality, private to the project in which they occur.

I do agree that you need to know what the method does, which value it returns, etc.; it's just that for the type of class I illustrated, I don't think you need a comment to tell you these things. In other cases - perhaps the type of class you are thinking of - you sometimes need to comment even a private method.

Of course, if enterprise Java were done using object orientation, these classes with no behaviour but only Javabean properties wouldn't exist. But that's another subject.

My post was only intended as a complaint about something that annoyed me, but the replies have made me realise that the lesson is this:
Whether or not a method depends on the method and its context, and is a decision that needs to be made intelligently by the developer. It can't be made by any wizard or quality metric, nor (IMO) by a blanket statement such as "All public API must have Javadoc comments."

Comment viewing options

Select your preferred way to display the comments and click "Save settings" to activate your changes.