Method Documentation – Is Obvious Information Necessary?

comments

I know we have questions about comments in general but I'm specifically wondering about Java Doc style method documentation here.

I've been pruning unnecessary comments as I refactor and I've noticed our code has painfully obvious descriptions of methods.

/**
* @name save
* @desc Validates and saves submitted daily plant production information.
*/

Most of the "documented" functions are just method names used by convention in our MVC framework (CakePHP). It's inherently obvious that the save method in the Production Controller performs the necessary actions to save Production Information.

We don't actually use Java Doc and I question the value of these descriptions even if they were included in Java Doc style documentation. The only reason I haven't touched these because they're method documentation that's supposed to be valuable. The method documentation also hasn't been used consistently, about half of our Controller/model methods are documented.

Is there any reason to keep these obvious "Java Doc" comments or should I prune them in favor of "self documenting code" and only make Java Doc comments for less obvious methods?

Best Answer

The point of javadocs is to provide information that isn't immediately obvious from just reading the method signature. Otherwise, it's just a waste of space. I disagree with the people who say that you shouldn't remove useless comments just for the sake of removing: those comments waste developer time, since the developers won't know that they're useless until after they read them. Go ahead and delete.

But an even better idea is to edit it so that it does provide useful information.

Before:

/** Sets the monkeyName field.
 * @param name - the monkey's name.
 */
public void setMonkeyName(String name) {

After: 

/** Validates and stores the monkey's name per RFC 420, Monkey Enterprise Data Protocol.
 * 
 * @throws IllegalArgumentException if the name fails validation
 */
Related Topic