Commentaires

10 min Niveau 2

Les commentaires, bien que théoriquement non interprétés, font pleinement partie des pratiques nécessaires à l’obtention d’un Clean Code. A titre personnel, j’aime à dire : “un bon commentaire est un commentaire inutile”. A toutes fins utiles, cette réplique n’est pas à prendre au pied de la lettre, mais reste néanmoins une bonne référence compte tenu de l’ensemble des attentions qu’ils impliquent.

La première étape d’un commentaire vise à s’assurer qu’il ne justifie pas un mauvais code. Mettre en commentaire des explications sur une variable ne vous dispense en rien de lui attribuer un nommage correct. Par contre, utiliser un commentaire pour apporter des informations supplémentaires non visibles instantanément est pertinent.

L’idée de base d’un commentaire est de permettre à n’importe quelle personne lisant votre code d’en faciliter sa compréhension. Ainsi, si une partie de votre code nécessite des explications spécifiques, alors l’utilisation des commentaires est requise. A contrario, si l’ensemble de votre code est lisible, clair, et compréhensible de tous, alors aucun commentaire n’est nécessaire. Rappeler cet état de fait peut sembler futile, mais c’est pourtant trop souvent qu’il est oublié lors de la rédaction de code…

Voici donc une liste non exhaustive des bons et mauvais commentaires, qui pourront vous servir de point de repère dans la réalisation de votre code.

Les bons commentaires

Les commentaires légaux, c’est-à-dire ceux qui sont situés au début de fichier et ont pour vocation de transmettre des informations quant au copyright, à l'auteur ou à la licence d’un script, font partie des bons commentaires. J’ai attendu trop longtemps à titre personnel avant d’en rédiger de la sorte, c’est dommage. La plupart de ces commentaires permettent un semblant d’information et de traçabilité, notamment à propos de la possibilité ou non de la réexploitation d’un code.

Les commentaires informatifs, comme décrits précédemment, sont bien évidemment encouragés. Attention cependant à ne pas tomber dans l’excès : l’information doit être juste, pertinente, et limitée. Ne vous perdez pas dans la description des conséquences d’une mauvaise utilisation d’une constante ou autre. Contentez-vous d’y décrire ce qu’elle doit contenir comme information.

Un autre aspect parfois négligé sur l’utilisation des commentaires consiste en l'explication des intentions de l’auteur. En effet, à chaque problème, il existe une multitude de solutions, et autant de manières différentes de coder chacune de ces solutions. Aussi un choix d’algorithme ou de logique peut être commenté dans le code afin que les lecteurs suivants comprennent la ou les raisons de votre décision.

La clarification est bien évidemment un des objectifs premiers des commentaires. Dans cet esprit, beaucoup de codes ne sont pas suffisamment précis sur les paramètres et/ou arguments des fonctions ou méthodes qu’ils définissent et utilisent. De la sorte, il peut paraître certaines fois complexe de savoir comment utiliser une méthode ou une fonction sans aller constater son code source. Privilégiez donc les commentaires permettant d’indiquer de manière précise quels sont les arguments attendus !

Les commentaires peuvent également permettre d’avertir un lecteur des conséquences d’un changement de valeur. Le but n’est pas ici de s’éterniser sur le sujet ou d’y décrire précisément tous les tenants et aboutissants attendus, mais bien de prévenir d’une possible dangerosité. Dans le même registre, le commentaire peut servir à amplifier la transmission d’un point important au lecteur du code.

Enfin, les commentaires TODO font bien partie des bons commentaires, puisqu’ils permettent d’éviter des oublis. Attention cependant à ne pas oublier de traiter ces points… Les développeurs qui n’utilisent que rarement ce système ont souvent tendance à en oublier quelques-uns…

Les mauvais commentaires

logo discord

Besoin d'aide ?

Rejoignez notre communauté officielle et ne restez plus seul à bloquer sur un problème !

En savoir plus