En milieu d'été, Antoine Vernois a publié un superbe article sur l'usage du commentaire dans le code : « Mythe : un code de qualité est largement commenté ».

Et il avait tout à fait raison.

Néanmoins, il manquait quelques éléments.
Dans le code source Unix originel, un commentaire a fait longtemps beaucoup glosé de lui, plus que du code qui l'entoure :

/* You are not expected to understand this */

La raison est historique, vestigiale, même : Le code en question date de 1975, intervient sur un élément relativement bas niveau, et à l'époque, on ne faisait pas de tests unitaire. Donc c'était à la fois une remarque pour dire que c'était un peu inutile de tenter à toucher ceci, surtout qu'il s'agissait d'un patch pour contrer un bug système.

Mais à cette époque, Unix tournait que sur d'immenses machines. Et il était possible d'en consulter le code source, contre une somme assez conséquente à verser aux Bell Labs. Vous imaginez la frustration des gens, non pas devant le côté frustre du patch en question, mais surtout devant ce commentaire qui a été vu à tord comme hautain.

Exemple récent dans un de mes javascripts : 

for(var i= 1 ; i<4 ; i++,c+='-')
{
	// ça c'est uniquement pour que Closure perde pas les pédales
}

Le compilateur Google Closure va supprimer le commentaire, et le bloc accolade qui est en fait inutile. Seulement, si je reviens deux ans après dessus, je me serais posé la question pourquoi je n'ai pas écrit beaucoup plus simplement for(var i= 1 ; i<4 ; i++,c+='-');.

Ce type de commentaire est là pour que quand je revienne des heures, jours, mois, années après, je comprenne pourquoi j'ai commis une telle aberration.
La réponse ne sera jamais de faire long, prolixe, verbeux, pompeux. Elle m'économisera de nombreuses minutes.

Mais si seulement il y avait que ça...

Là où manquent les commentaires

Parce que les projets devenaient immenses et qu'on avait de multiples intervenant autour d'un code source, on vit se populariser dans les années 1980s l'idée du code auto-documenté. L'idée était louable : obliger à des convention d'écritures, à une rigueur de nommage, et ceci indépendamment des langages et des frameworks utilisés.

Hélas, l'enfer est pavé de bonnes intentions, et on a vu n'importe quoi arriver. À savoir, la suppression pure et simple de tout commentaire. J'ai vu du code pondu comme ça, et comment dire… Je me suis mis dans le cerveau de la poule qui trouve un couteau (cela n'a rien à voir avec Clara Morgane).

Je vous jure que sur un projet, j'ai perdu une demi-journée à cause d'un idiot qui a très mal compris le concept du code auto-documenté, et qu'il l'a appliqué d'une manière quasi intégriste.

couverture des éditions francophone des deux romans de Gibson
« Code source » est la suite de « Identification des schémas ».
Ce ne sont pas des manuels, mais des polars de William Gibson, pape cyberpunk vénéré.

Actuellement, je suis super emmerdé quand je me retrouve face à des langages descriptifs qui n'acceptent pas les commentaires.
Si, cela existe. Exemple : le format JSON. À moins de space-encoder votre commentaire, point d'issue pour y mettre une information contextuelle.

Ou alors les méta-données du document source, mais même les éditeurs sous Mac n'ont pas ça.

Ça me fait penser qu'une interface “auto-documentée”, donc sans documentation, ben ça peut marcher. Néanmoins, il faut rester réaliste : au-delà d'une certaine échelle, c'est même pas envisageable. Songez aux utilisateurs qui n'ont forcément pas le code sous-jacent en tête : documentez toujours.

On peut commenter pour ne rien faire avancer

Tiens, dans le cadre d'un travail en équipe, faut-il que vos collègues qui ne travaillent pas la mécanique comprennent vos commentaires ? Bien sûr que non :

(NOTE : ce qui suit est une fiction)

Grâce à ce genre de commentaires, vous gagnez l'estime muette de vos collaborateurs qui en restent admirativement coïts devant tant d'auto-suffisance de sagesse. Les commentaires évitent les questions stupides.

C'est comme l'écriture d'un médecin : c'est illisible, cela entretient le mystère.

Ce qu'il y a dans mes commentaires

Le commentaire ? J'en mets.
J'use et j'abuse de JavaDoc, la notation qui permet aux IDE de comprendre ce que font vos fonctions. C'est un réflexe (quoique pas systématique), et il m'est bien utile.

Souvent, mes commentaires dans le code source comportent des indications techniques, des liens vers des url de référence, vers des rapports de bugs. Il comporte aussi extrêmement souvent du code mort, même en cas de versionnage. C'est un intron de l'ADN de mes productions, à l'importance non-dite. Voyez-y des ratures, du Tipp-Ex, des notes au crayon sur le tapuscrit d'un roman. Et des fois, il n'est pas inutile de prendre la place que rêvait Fermat.

Les commentaires dans un code source sont aussi utiles que les README d'un tgz, les messages de commits d'un projet sous Git, un rapport de bug.

Le commentaire du code source est une enluminure. Celui du code généré, une information qui n'intéressera que les mainteneurs du site.

Quoique…
Je viens de mettre un commentaire dans mon site corporate. On ne sait jamais, si un curieux de la profession y jette un œil…