Comment écrire de bons commentaires de code: "pourquoi", pas "comment"

Bonjour, Habr! Je présente à votre attention la traduction de l'article "Ecrire de bons commentaires: le pourquoi, pas le comment" de Jack Franklin.







Commenter du code dans un environnement de programmation est souvent considéré comme une perte de temps ou comme un signal que le code peut être amélioré. Voici une citation du fichier CONTRIBUTING.md que j'ai trouvé sur GitHub (et il y a beaucoup d'exemples de ce type):

Les commentaires doivent être évités. Si votre code ne peut être compris sans commentaires, réécrivez-le pour s'expliquer.

Je crois que dans la plupart des cas, ces conseils seront infructueux et incorrects. Je crois que cette approche a ses racines dans les expériences d'apprentissage de la plupart des gens qui ont étudié la programmation. Quand j'ai étudié l'informatique à l'université (bien que ces conseils se retrouvent dans de nombreux cours, pas nécessairement universitaires), je me souviens très bien au premier semestre d'un enseignant qui a dit:

Chaque ligne de code doit avoir un commentaire expliquant ce qu'elle fait. Votre travail dans le cours sera évalué par rapport à ce critère.

Alors, disons que vous êtes un étudiant fraîchement sorti du four qui commence tout juste ce cours. Qu'est ce que tu vas faire? Commentez le code, bien sûr!

//      bar
const inputValue = process.ENV.bar

//     2
const newValue = inputValue * 2

//     square
const finalValue = square(newValue)

//         
const square = (x) => x * x

Les gens qui disent que les commentaires sont mauvais pensent en fait à des commentaires comme celui-ci. Et ils ont absolument raison! Les commentaires comme ceux ci-dessus qui répondent à la question «comment?» Dans la programmation sont complètement inutiles. Tous ces commentaires n'ont rien ajouté au code qui ne puisse être compris à partir du code lui-même.

Répondez à la question "pourquoi?"

Le problème avec les commentaires ci-dessus est qu'ils expliquent comment . Explique les étapes que nous suivons dans le code. De tels commentaires sont rarement utiles; le code lui-même est bien meilleur pour vous dire quoi faire. Après tout, les lignes de code ne sont que des instructions qui indiquent à l'ordinateur comment effectuer une tâche.



Habituellement, il n'y a pas besoin d'une abondance de commentaires, car vous pouvez écrire du code simple sans fonctionnalités ni nuances qui lui donneraient un aspect incompréhensible. Mais parfois, des situations surviennent lorsqu'il est impossible d'écrire du code élémentaire et intuitif. C'est peut-être un bogue que vous devez contourner. Ou vous avez hérité du bonheur d'anciens développeurs sous la forme d'un système qui ne vous permet pas de résoudre le problème comme vous le souhaiteriez. Ou, à la fin de la journée, il n'y a tout simplement pas de moyen facile d'améliorer votre code.



Une fois, j'ai travaillé dans une entreprise de transformation. Chaque jour, nous exécutions une énorme requête SQL qui sélectionnait les paiements à payer. La requête était bien optimisée - nous avions besoin qu'elle soit très rapide - et extrêmement complexe à cela, avec de nombreux cas extrêmes à prendre en compte. Nous nous sommes efforcés de le rendre aussi clair que possible. Cependant, cette demande ne pourra jamais être totalement intuitive et facile à comprendre. Il contenait simplement trop de code avec un tas de conditions et de logiques qui ne pouvaient être comprises que dans le contexte de notre entreprise et de son fonctionnement.



Je voulais trouver un exemple à montrer ici, alors je suis allé dans la nature de la base de code React pour trouver quelque chose. Vous n'avez pas besoin d'être un développeur React pour le comprendre. Alors, voici le code que je voudrais mettre en évidence:

//  key     .    , 
//  key      (, <div {...props} key="Hi" />
//  <div key="Hi" {...props} /> ).     key,   ,
//      jsxDEV   , 
// <div {...props} key="Hi" />,       ,
//    key   . 
if (maybeKey !== undefined) {
  key = '' + maybeKey
}

( Et voici un lien vers celui-ci sur GitHub ).



Faites attention au code lui-même:

if (maybeKey !== undefined) {
  key = '' + maybeKey
}

Il n’est pas si difficile de comprendre ce qu’il fait. Si MaybeKey n'est pas spécifié, nous attribuons la valeur peut-être stringifiée à key. Remarque: c'est une petite astuce JavaScript - cela '' + maybeKeyconvertira le contenu de MaybeKey en chaîne.



Mais ici, toute la question est de savoir pourquoi . Le commentaire sur ce code est excellent. Il souligne le problème, donne deux exemples et explique également comment résoudre ce problème à long terme et ce que nous faisons à court terme.



Si vous voulez regarder un commentaire que j'ai laissé dans le code que j'ai écrit, en voici un (TypeScript / Closure Compiler) . C'est un bon exemple du type de commentaires que je trouve très précieux.



En fin de compte, n'importe quel code peut être compris. Après tout, le code n'est rien de plus que des instructions qui indiquent à l'ordinateur comment procéder. Le code peut prêter à confusion, mais il ne peut pas mentir; si le temps est suffisant, tout développeur peut parcourir le code étape par étape et comprendre ce qu'il fait. Il est parfois beaucoup plus difficile de comprendre pourquoi il le fait. Laissez donc à vos collègues (ou à votre futur vous-même dans six mois) un certain contexte sur pourquoi et pour quoi votre code fait ce qu'il fait. Ce sera bien mieux.