Il y a étonnamment beaucoup de débats passionnés en cours dans la communauté des développeurs sur l'utilité ou l’envie d’avoir des commentaires dans le code source. Le code doit-il inclure des commentaires significatifs ou ne pas en contenir du tout, ou quelque chose entre les deux?

Les commentaires sont définis comme les lignes de texte qui sont ajoutées au code source après un marqueur d'un certain langage pour indiquer un texte non fonctionnel qui est explicitement ignoré par le compilateur ou l'interprète.

Objectif des commentaires

L'une des raisons pour lesquelles les développeurs écrivent des commentaires dans leur code: ils reflètent l'intention.

Tout commentaire doit décrire ce que le développeur a l'intention de faire comme objectif ou résultat de la section de code. Mais malgré cela, les commentaires ne doivent jamais répéter la fonctionnalité du code.

Contre les commentaires

Certains développeurs préconisent fortement de commenter le moins possible, voire pas du tout. L'un des principaux arguments est le dicton suivant : "Un bon code est auto-documenté". Il se base sur le fait que le code commenté est souvent plus difficile à comprendre que le code sans commentaire. Mais il existe encore un certain nombre de raisons pour lesquelles les développeurs refusent de commenter :

Le temps. Les commentaires prennent beaucoup de temps, tout comme leur support. Les développeurs préfèrent passer du temps non pas à expliquer leur code, mais à l'écrire.

L'incongruité. Avec le temps, les commentaires peuvent mentir par inadvertance, ce qui peut conduire à une interprétation incorrecte du code.

Longueur. Les commentaires allongent le fichier et peuvent souvent créer un encombrement inutile, ce qui prend plus de temps à lire.

Répétition du code. Les commentaires tentent souvent d'expliquer "quoi et comment", ce qui tend à répéter le code. Les commentaires doivent toujours indiquer "pourquoi".

Caractère concret. Il est difficile d'écrire des commentaires clairs et non cryptiques, et encore plus de les interpréter. Si le code a été écrit de manière confuse, le commentaire sera probablement le même.

Incohérence. Parfois, les commentaires sont écrits par des développeurs qui comprennent mal le code et renforcent cette incompréhension par un texte incorrect ou trompeur.

Pour les commentaires

Les commentaires intentionnels présentent des avantages malgré leurs inconvénients. Tout d'abord, les commentaires aident la personne qui les a écrits. Ensuite, et ce n'est pas la moindre des raisons, ils peuvent faciliter la compréhension des autres.

Le temps nécessaire pour lire et comprendre le code est réduit

Comme vous savez ce qui va se passer grâce aux commentaires, vous disposez d'une base pour interpréter cette section du code. Cela peut être particulièrement utile si vous essayez de vous remettre sur les rails après une pause.

Trouver une section fonctionnelle spécifique du code devient plus facile

Il sera plus facile de trouver un code spécifique dans un grand projet inconnu s'il contient des commentaires. Sans eux, vous devrez consulter des centaines et des milliers de fichiers et passer du temps à les lire. Les outils de recherche ne sont utiles que si vous pouvez deviner le nom de la fonction. Les commentaires intentionnels vous donnent un point d'appui.

Vous pouvez reconstituer les schémas de pensée du développeur

Un commentaire pertinent avec intention répond à la question : "Qu'est-ce que le développeur précédent allait faire ici?".

L'écart entre l'intention commentée et le résultat réel du code indique des erreurs potentielles

L'erreur est plus facile à détecter si le code contient un commentaire d'intention. Par exemple, le développeur avait l'intention de faire une chose, et le code ne correspondait pas à ces intentions.

Les non-programmeurs peuvent également participer

Le gestionnaire, le client, le concepteur, l'utilisateur de logiciels libres, etc. pourront également consulter vos commentaires et mieux comprendre ce qui se passe. Comme les commentaires sur les intentions sont indépendants de la langue, ils constituent une base pour un retour d'information utile.

Le code devient automatiquement un tutoriel

Les stagiaires peuvent lire certaines sections du code avec des commentaires s'ils ne comprennent pas quelque chose. Cela leur permettra d'apprendre même des modèles et des algorithmes avancés et complexes.

Le débat sur les commentaires dans le code n'est pas nouveau. Il existe de solides arguments pour et contre. Oui, les commentaires font perdre du temps au développeur lors de l'écriture, mais font gagner du temps aux autres lors de la compréhension du code à un stade ultérieur. L'essentiel est d'ajouter des commentaires significatifs pour améliorer la lisibilité du code.