Qu’est-ce qu’un bon commentaire ? Cette question me fait penser à une petite anecdote qui s’est produite quand j’ai commencé a travaillé en 2001 dans une grande entreprise, dans un service composé d’un vingtaine de développeurs. Je me souviens qu’il y avait une personne qui s’appelait Patricia et qui avait pour rôle de relire le code des autres développeurs et de rajouter des commentaires. Le chef du service avait constaté que le code était devenu difficile à maintenir et que l’une des causes était le manque de commentaires. Patricia m’avait dit qu’il lui avait alors demandé d’en mettre à chaque ligne ! J’avais trouvé ça surprenant, mais je m’étais rangé à l’idée que c’était probablement une bonne chose à faire dans les grands projets. Après quelques semaines je suis tombé sur les bouts de code que Patricia avait repris. Elle avait bien fait son travail, chaque ligne était commentée. Ca donnait un truc du genre :

// classe Machin
public class Machin {
     private int Total; // le total
     private int Type; // le type
...

Quelque temps après j’ai reparlé avec Patricia. Elle me confiait que c’était le travail le plus pénible et le plus inutile qu’elle ait eu à faire.

Voici ce qu’en dit Robert C. Martin : « Rien ne peut être plus utile qu’un commentaire bien placé. Rien ne peut encombrer un module autant que des commentaires dogmatiques sans importance. Rien ne peut être plus préjudiciable qu’un ancien commentaire obsolète qui propage mensonges et désinformation.

Les commentaires ne sont pas comme la liste de Schindler. Ils ne représentent pas le « bien parfait ». Les commentaires sont, au mieux, un mal nécessaire. Si nos langages de programmation étaient suffisamment expressifs ou si nous avions suffisamment de talent pour les manier de manière à exprimer nos intentions, nous n’aurions pas souvent besoin des commentaires, voire jamais.

Les commentaires sont bien employés lorsqu’ils pallient notre incapacité à exprimer nos intentions par le code. Notez que j’emploie le mot incapacité, car les commentaires masquent toujours nos échecs. Nous en avons besoin car nous ne parvenons pas toujours à nous exprimer sans eux, mais nous ne devons pas être fiers de les utiliser.

Par conséquent, lorsque vous éprouvez le besoin d’écrire un commentaire, réfléchissez et essayez de trouver une solution pour exprimer vos intentions avec du code. Chaque fois que le code parvient à transmettre vos intentions, vous pouvez vous féliciter. Chaque fois que vous écrivez un commentaire, faites la grimace et ressentez le poids de l’échec.

Pourquoi un tel refus des commentaires ? Simplement parce qu’ils mentent. Pas toujours, pas intentionnellement, mais beaucoup trop souvent. Plus un commentaire est ancien et placé loin du code qu’il décrit, plus il risque d’être totalement faux. La raison en est simple. En toute bonne foi, les programmeurs ne peuvent pas les maintenir.

Le code change et évolue. Des pans entiers peuvent être déplacés d’un endroit à un autre. Ces morceaux se séparent, se reproduisent et se réunissent à nouveau pour former des chimères. Malheureusement, les commentaires ne suivent pas toujours ces modifications, ou ne peuvent tout simplement pas. Trop souvent, ils sont séparés du code qu’ils décrivent et se transforment en un texte orphelin dont la justesse s’étiole au fur et à mesure.

Je suis d’accord, les programmeurs devraient être suffisamment disciplinés pour garder des commentaires à jour, pertinents et justes. Cependant, cette énergie est mieux employée lorsqu’elle permet d’obtenir un code tellement clair et explicite que les commentaires en deviennent inutiles.

Les commentaires inexacts font beaucoup plus de mal que l’absence de commentaires. Ils trompent et induisent en erreur. Ils fixent des attentes qui ne seront jamais satisfaites. Ils établissent d’anciennes règles qui n’ont plus besoin d’être suivies ou qui ne doivent pas l’être.

La vérité doit se trouver uniquement dans le code. Seul le code peut indiquer réellement ce qu’il fait. Il représente la seule source d’informations absolument justes. Par conséquent, bien que les commentaires puissent parfois être nécessaires, il est indispensable d’œuvrer à leur extinction. »