En tant que développeurs, nous avons tous déjà entendu dire qu’il est crucial de commenter abondamment le code pour le rendre plus clair et compréhensible. Mais les commentaires de code sont-ils vraiment la solution pour obtenir une meilleure compréhension ?

Dire la même chose que le code dans les commentaires, mais pourquoi ?

Si vous avez une variable customerId, allez-vous mettre un commentaire au dessus pour dire « Ceci est la variable pour l’identifiant de client » ?

Honnêtement, cela n’apporte aucun intérêt. Les commentaires peuvent avoir pour inconvénient d’être redondants et de répéter ce que le code dit déjà de manière claire.

Un commentaire « Incrémenter le compteur » sur une ligne de code faisant compteur++ n’apporte aucune valeur ajoutée. Ce genre de commentaire peut engendrer le désordre dans le code plutôt que de le rendre plus compréhensible.

Les commentaires deviennent obsolète !

Et si je vous disais que les commentaires dans votre code peuvent être obsolètes au fur et à mesure du temps.
Le code est souvent amené à changer, mais les développeurs pensent-ils réellement à mettre à jour les commentaires ?
Ce n’est pas sûr, rien ne le lui oblige !

Des commentaires non mis à jours sur un code induisent en erreur les prochains développeurs qui comptent sur les commentaires pour comprendre ce que vous avez fait.

Les commentaires alourdissent la compréhension du code

Les commentaires sur du code déjà clair et lisible viennent encombrer la compréhension du code, cela ne fait qu’ajouter du bruit. Des commentaires expliquant chaque ligne de code apportent une gêne en plus lors de la maintenance d’une application. Si des commentaires doivent être écrits, ils doivent se concentrer sur les aspects non évident du code, fournir des informations supplémentaires sur le contexte et expliquer des décisions de conception. Les commentaires doivent ajouter de la valeur et doivent être utilisés à bon escient !

Ecrire un commentaire dans mon code ? Considérez cela comme un échec

Si les commentaires ne fournissent pas de valeur ajoutée significative dans votre application, quel est l’intérêt de les mettre ?
Je pense que le surplus de commentaires va seulement rendre votre code moins lisible.

Si un commentaire est nécessaire, c’est probablement que votre code n’est pas assez clair et qu’il doit être remanié. Considérez cela comme un échec en tant que développeur et faites en sorte que votre code soit plus clair. Améliorez-vous de jour en jour !

Un code auto documenté à la place des commentaires

Un code bien écrit, structuré de manière logique et utilisant des noms de variables et fonctions explicites est déjà une documentation ! Cela peut s’appeler du « code auto-documenté ».

Les commentaires dans le code sont souvent redondants si le code est clair et lisible. Après tout, le code lui-même devrait être suffisamment expressif pour expliquer son fonctionnement !

Posez-vous les bonnes questions.