Dans son livre Robert C. Martin recense 18 types de mauvais commentaires. Certains cas sont des évidences, d’autres concernent la documentation du code, et les derniers sont des pratiques carrément moyenâgeuses. La lecture reste tout de même très intéressante ! Attardons nous sur un cas qui revient souvent :

« Mettre du code en commentaire

Peu de pratiques sont aussi détestables que la mise en commentaire d’un bout de code. Ne le faites jamais !

InputStreamResponse response = new InputStreamResponse();
response.setBody(formatter.getResultStream(), formatter.getByteCount());
// InputStream resultsStream = formatter.getResultStream();
// StreamReader reader = new StreamReader(resultsStream);
// response.setContent(reader.read(formatter.getByteCount()));

Ceux qui tombent sur du code en commentaire hésitent souvent à le retirer. Ils supposent qu’il doit y avoir une justification à sa présence et qu’il est trop essentiel pour être éliminé. Au fil du temps, le code commenté s’entasse, à l’image des sédiments au fond d’une bouteille de vin médiocre.

Examinons le code suivant :

this.bytePos = writeBytes(pngIdBytes, 0);
//hdrPos = bytePos;
writeHeader();
writeResolution();
//dataPos = bytePos;
if (writeImageData()) {
  writeEnd();
  this.pngBytes = resizeByteArray(this.pngBytes, this.maxPos);
} else {
  this.pngBytes = null;
}
return this.pngBytes;

Pourquoi ces deux lignes de code sont-elles désactivées ? Sont-elles vitales ? Étaient-elles là comme un rappel pour une modification future ? Ou est-ce juste un vestige du passé, commenté depuis une éternité et oublié ? Dans les années 1960, garder du code en commentaire avait peut-être sa place. Mais aujourd’hui, avec des outils comme GIT, il n’y a aucune excuse. Ces outils sauvegardent chaque fragment de code pour nous. Laisser du code en commentaire ? C’est du passé. Supprimez-le sans crainte, rien ne se perd.

Vous avez ma parole. »

Laissons le débat ouvert un instant : Le code en commentaire est parfois très utile quand on refactor du code ou que l’on est au milieu d’un problème et qu’on n’a pas encore une vision claire de la façon dont le code va finir par se structurer. Il y a aussi certains cas où garder un petit bout de code que l’on va utiliser pour s’aider en phase développement peut être pratique. Ces cas doivent rester éphémères.

Il y a aussi le cas des procédures stockées SQL. Les commentaires sont très utiles tant que l’on est en train de créer une procédure. Par contre, une fois le travail terminé, il est souvent possible de se débarrasser d’une bonne partie du code commenté avant d’enregistrer la procédure. Juste, peut-être garder certains cas de test ou de préparation de données-types ou particulières qui facilitent la maintenance de la procédure.