Over a million developers have joined DZone.
Silver Partner

Autogenerated Comments Rant

· Java Zone

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.)
Topics:

{{ parent.title || parent.header.title}}

{{ parent.tldr }}

{{ parent.urlSource.name }}