Dois-je écrire des commentaires?

Réflexions sur commenter le code et commenter de la bonne manière

On nous dit souvent que les commentaires sont très importants. Les commentaires sont une partie importante et importante de la programmation. En tant que débutant, il est difficile de juger et de déterminer le nombre de commentaires à ajouter et ce qu'il faut écrire dans les commentaires!

C'est l'une des choses qui ne sont pas figées dans la pierre, tout le monde semble avoir une opinion différente et contrastée, ce qui vous laisse dans une limbe remplie d'insécurité.

Voici ma ligne de pensée:vous devriez écrire des commentaires, aussi peu que possible, pour expliquer vos décisions.

Disséquons ceci.

Votre code doit être explicite, autant que vous le pouvez.

Les langages de haut niveau comme JavaScript ou Python sont très lisibles. Vous pouvez presque lire le code à haute voix et penser que c'est du simple anglais, si vous nommez correctement vos variables et méthodes.

Certaines choses vont demander plus de réflexion, mais même si le code est un peu complexe, tant qu'un programmeur peut le lire et déterminer à 100% ce que fait le code, il ne devrait pas avoir besoin de commentaires.

Vous avez besoin de commentaires lorsque vous devez expliquerPourquoid'une instruction ou d'un bloc particulier. Pas leQuel, cela devrait être déduit du code. Nous l'appelons haut niveau pour une raison: c'est du code auquel nous pouvons penser. Ce n'est pas du langage machine ou de l'assemblage, ce qui est très très difficile à lire et à comprendre.

Certains blocs de votre code nécessiteront des commentaires pour en expliquer d'autres, oumême toi,Pourquoivous faites une chose particulière. Pas toujours bien sûr, pas quand c'est évident.

Même 6 mois plus tard, si vous travaillez sur une partie distincte de la base de code, puis revenez à cette ligne de code, vous ne vous souviendrez probablement pas de tout ce qui était en jeu lorsque vous l'avez édité. Vous vous souvenez peut-être de 90% des raisons pour lesquelles vous avez ajouté quelque chose, mais il y avait autre chose que vous ne pouvez pas trouver ... un commentaire serait parfait pour cela.

Le code n'est pas que des instructions et des commentaires. Souvent, vous pouvez voir pourquoi une ligne de code a été ajoutée grâce au contrôle de code source (Git). Vous regardez la ligne dans votre application Git, et l'historique de cette ligne vous dira pourquoi vous ou votre collègue l'avez modifiée il y a 10 mois. Si le message de validation de Git était utile et détaillé, pas «Corriger le bogue». C'est aussi une bonne documentation, particulièrement bonne dans les projets Open Source qui peuvent amener de nombreuses personnes à toucher la base de code.

Si vous êtes à un entretien d'embauche et que vous vous demandez «dois-je ajouter des commentaires dans mon exercice?» la réponse est toujoursOui.

Vont-ils probablement vous juger pour vos commentaires et pour votre code? Et ce que vous écrivez dans les commentaires aussi.

Je le ferais certainement. Peu importe à quel point vous pouvez être un assistant de code, l'entreprise doit peut-être vous licencier dans 3 mois et la prochaine personne à venir vous remplacer devra comprendre votre code, car c'est un atout de l'entreprise. Ils ne peuvent pas vraiment se permettre d'embaucher quelqu'un qui n'est pas disposé ou capable d'avoir de l'empathie pour les autres personnes qui essaient de lire le code source.