Nouvel article que je tire du contenu du livre 97 choses que tout programmeur devrait savoir.

Cal Evans, qui a écrit l’article de base en anglais, y parle des commentaires.

Voici le contenu traduit de l’article :

Dans ma première classe de programmation au collège, mon professeur a remis deux fiches de codage BASIC. Au tableau, la mission était : « Écrivez un programme qui saisit 10 scores de bowling et en fait une moyenne. » Ensuite, le professeur a quitté la salle. Quelle difficulté pourrait-il être? Je ne me souviens pas de ma solution finale, mais je suis sûr qu’elle nécessitait une boucle FOR / NEXT et ne pouvait pas dépasser 15 lignes au total. Les feuilles de codage – pour vous, les enfants qui lisent ceci, oui, nous écrivions du code avant d’être autorisé à enregistrer, dans un ordinateur, environ 70 lignes de code chacun. J’étais très confus quant à savoir pourquoi l’enseignant nous aurait donné deux feuilles. Comme mon écriture a toujours été atroce, j’ai utilisé la seconde pour recopier mon code très soigneusement, en espérant obtenir quelques points supplémentaires pour le style.

À ma grande surprise, lorsque j’ai reçu la mission au début de la prochaine classe, j’ai reçu une note très moyenne. (Ce fut pour moi un souci pour le reste de mon temps au collège.) Le commentaire au dessus de mon code était «Pas de commentaires ?»

Il n’était pas suffisant que, le professeur et moi-même, savions ce que le programme devait faire. Une partie de la mission était de m’apprendre ceci : mon code devait être compréhensible au prochain programmeur venant après moi. C’est une leçon que je n’ai jamais oubliée.

Les commentaires ne sont pas mauvais. Ils sont nécessaires à la programmation autant pour les branchements de base que pour les constructions en boucle. La plupart des langues modernes ont un outil similaire à javadoc, qui analysera correctement les commentaires formatés pour créer automatiquement un document API. C’est un très bon début, mais pas assez. Dans votre code, vous devez expliquer ce que le code devrait faire. Coder selon le vieil adage: «S’il était difficile à écrire, il devrait être difficile à lire», déservira votre client, votre employeur, vos collègues et votre avenir.

D’autre part, vous pouvez aussi aller trop loin dans vos commentaires. Assurez-vous que vos commentaires expliquent votre code mais ne l’obscurcissent pas. Saupoudrez votre code de commentaires pertinents, expliquant ce que le code est censé accomplir. Vos commentaires d’en-tête devraient donner à tout programmeur suffisamment d’informations pour utiliser votre code sans avoir à le lire, alors que vos commentaires en ligne devraient aider le prochain développeur à le réparer ou à l’étendre.

Dans un même travail, je peux ne pas être d’accord avec une décision de conception prise par ceux qui me l’ont indiqué. Je me suis senti plutôt sarcastique, comme le sont souvent les jeunes programmeurs, j’ai copié-collé le texte, issu du courrier électronique de la personne qui m’a demandé d’utiliser leur conception, dans le bloc de commentaires d’en-tête du fichier. Il s’est avéré que les gestionnaires de ce magasin en particulier ont révisé le code lors de leur engagement. C’était ma première introduction au terme de changement de carrière.