Code trop commenté : signe de mauvaise qualité ?

Les commentaires de certains programmes m'ont toujours surpris : Soit il n'y en a pas, soit il y en a trop ... Je suis toujours surpris par la quantité de commentaire de certains programmes, surtout lorsque ceux ci n'apportent rien et qu'ils polluent la lecture du code. 

En réalité, et au risque d'en faire bondir certains, il est préférable d'avoir peu de commentaires dans du code bien écrit, plutôt que l'inverse.
D'ailleurs, une méthode trop commentée est même peut-être un signe que quelque chose est louche, comme le dit si bien Martin Fowler.

Ne vous inquiétez pas, je ne dis pas que les développeurs ne devraient pas écrire de commentaires. Dans notre analogie olfactive, les commentaires ne sentent pas mauvais ; en fait ils sentent plutôt bon. La raison pour laquelle nous mentionnons les commentaires ici est qu'ils sont souvent utilisés comme déodorant. C'est étonnant de remarquer que souvent, un code généreusement documenté est en fait vraiment mauvais.

Les commentaires nous guident vers du mauvais code qui a toutes les mauvaises odeurs dont nous avons discuté dans le reste de ce chapitre. Notre première action est de supprimer cette "mauvaise odeur" en refactorant. Et dès que nous avons fini, nous nous rendons compte que les commentaires sont superflus.

Si vous avez besoin d'un commentaire qui explique ce qu'un bloc de code fait, essayez d'extraire la méthode. Si la méthode est déjà extraite mais que vous avez toujours besoin d'un commentaire pour expliquer ce qu'elle fait, alors renommer la. Si vous avez besoin de définir quelques règles à propos de l'état du système, introduisez des assertions.

Quand vous sentez le besoin d'écrire un commentaire, essayez d'abord de refactorer le code pour que chaque commentaire devienne superflu. Un bon endroit pour utiliser un commentaire est quand vous ne savez pas quoi faire. En plus de décrire ce qu'il fait, les commentaires indiquent les points sur lesquels vous n'êtes pas sûr. Un commentaire est une bonne place pour dire pourquoi vous avez fait quelquechose. Ce type d'information aide les futurs développeurs qui reprendront votre code, et spécialement ceux qui oublient vite.

Martin Fowler

Avoir un outil de qualimétrie (type Sonar) qui oblige les développeurs de mettre des commentaires Javadoc peut donc être contraignant sur certains aspects car il peut pousser à mettre du commentaire superflu sans aucune valeur ajoutée, car cet outil ne fait qu'une analyse du code source sans intelligence, sans contexte.

Quelques contre-exemples assez problématiques (issus de vrais code source sur de vrais projets !!) sur les accesseurs :

/**
* Accesseur en écriture sur l'attribut Name
* @param newName Nouveau nom à assigner à l'attribut name **/
public String setName(String newName) {
    this.name = name;
}
/**
* Accesseur le lecture sur l'attribut Name
* @return l'attribut Name
*/
public String getName() {
    return this.name;
}

Ou dans certains cas, quand un développeur prend conscience du peu d'intérêt du commentaire mais DOIT respecter les règles imposées par l'outil de qualimétrie (Sonar en l'occurence dans l'exemple suivant) et sort l'astuce du point commenté pour le code soit sans violations !

/**
* .
**/
public int getName() {
    return this.name;
}

En réalité le code des accesseurs est beaucoup plus lisible sans aucun commentaire : 

public void setName(String name) {
    this.name = name;
}

public int getName() {
    return this.name;
} 

Ceci nous amène à plusieurs règles pour l'écriture de bons commentaires :

1. Privilégiez le pourquoi et non pas le comment. Documentez les classes et les opérations pour décrire leurs effets et leurs objectifs sans référence aux moyens par lesquels ils le font. Le commentaire ne doit pas faire référence aux détails d'implémentation (Cette règle s'applique également en tant que règle de nommage des classes et opérations).
2. Ne dupliquez pas les commentaires entre les interfaces et les classes d'implémentations. En cas de refactoring, il sera difficile de maintenir une documentation à jour aux différents endroits. Il est préférable de positionner le commentaire sur l'interface et de laisser la classe d'implémentation sans commentaire. 
3. Privilégiez la concision des commentaires. N'oubliez pas qu'un commentaire est rarement lu, surtout s'il est long. Il est préférable de vérifier automatiquement la validité de paramètres dans le code avec des assertions plutôt que d'écrire dans le commentaire ce qui est attendu.
4. Privilégiez les conventions de codage pour comprendre l'objectif d'une méthode. Par convention, on sait qu'une méthode commençant par get est un accesseur en lecture. Même chose avec les méthode set qui indique un accesseur en écriture. Il n'est pas nécessaire de ré-expliquer un comportement dont la lecture du code saute aux yeux !
5. Privilégiez un vocabulaire commun à tous les développeurs pour que chacun puisse appréhender rapidement le sens d'une fonction juste en lisant son nom. En réalité, il est préférable de nommer correctement une méthode plutôt que d'écrire du commentaire pour expliquer ce qu'elle fait. Il peut être utile de définir une liste de mot-clés à utiliser pour que les développeurs s'appuient sur une même convention de codage.
6. Prenez du recul sur le besoin d'un commentaire. Ne vous forcez pas à écrire un commentaire parce que l'outil de qualimétrie a remonté une violation, ou parce qu'un taux de commentaire minimal n'est pas respecté. Posez vous la question "Est ce que ce commentaire a une valeur ajoutée ?" si la réponse est non, alors supprimer le !  

L'info en plus : Personnaliser cette règle sous Sonar

• La Javadoc n'est pas requise sur une méthode annoté @Override. Le commentaire sera automatiquement hérité. (Privilégiez cette approche à l'utilisation de inheritDoc qui nécessite un commentaire). N'hésitez donc pas à en tartiner les méthodes déjà commentées dans les interfaces et dans les classes parentes (notamment equals, hashCode, toString, etc.);
• le paramètre allowMissingPropertyJavadoc de Sonar permet de ne pas remonter d'erreurs pour les getter et setter non commentés.

Pour aller plus loin, je vous conseille les lectures suivantes :

• Refactoring, Improving the design of existing code, de Martin Fowler (p110)
• Est ce que la Javadoc doit être ajoutée à l'implémentation ? sur StackOverflow
• 5 raisons de ne pas utiliser de JavaDoc sur votre prochain projet de Markus Sprunk
• Domain Driven Design de Eric Evans (p247)