3 minutes

Cette question revient régulièrement lorsque vous développez un logiciel, que vous suiviez les méthodes DevOps ou non ! Les commentaires permettent de rendre votre code facilement compréhensible pour tous développeurs extérieurs au projet, sans enlever à sa lisibilité. Si vous n’utilisez pas les commentaires avec parcimonie, votre code peut rapidement se transformer en un cauchemar. C’est pourquoi nous avons résumé toutes nos bonnes pratiques dans cet article ! 👇🏻

Recommandation pour rédiger de bons commentaires

Voici une liste de conseils que vous pouvez appliquer (ou non) afin de rédiger des commentaires utiles au bon endroit. Bien entendu, vous pouvez également les adapter à vos besoins et rédigez vos propres règles !

Règle n°1 : un bon commentaire dit ce que le code ne peut pas

Cela peut sembler évident : votre commentaire doit apporter des informations que votre code ne peut présenter. Cela peut être une spécification sur le pourquoi de l’utilisation d’une fonction, un détail sur la manière dont votre code est construit…

Mais attention ! Avoir des commentaires dans votre code ne justifie pas que votre code soit brouillon et mal rédigé. Par exemple, pensez à donner à vos fonctions des noms clairs et précis.

Voyez ci-dessous un exemple de commentaires n’apportant pas de valeur ou d’explication à votre code 👇🏻

Commentaires dans le code : l'exemple à ne pas suivre

Et voici un exemple à suivre :

Commentaires dans le code : l'exemple à suivre

Règle n°2 : si vous ne pouvez pas écrire un commentaire simple, le problème vient sûrement de votre code.

Comme nous l’avons expliqué précédemment, un commentaire apporte du contexte, mais ne doit pas répéter une information déjà existante dans votre code. Bien entendu, ajouter des détails sur l’implémentation d’une variable est utile. Cependant, si votre code a été écrit proprement, il doit être compréhensible sans commentaire.

Dit autrement : vous n’avez pas besoin d’ajouter un commentaire pour expliquer ce que fait votre fonction si le nom de cette fonction est clair. Si vous avez l’impression que la personne qui lira votre code ne comprendra pas à quoi celui-ci sert, peut-être faut-il se pencher sur votre code plutôt que d’ajouter 3 lignes de commentaires.

Vous trouverez ci-dessous un exemple de ce qu’il ne faut pas faire 👇🏻

Commentaires dans le code : l'exemple à ne pas suivre

Regardez ici comment cette fonction aurait pu être nommée et le code rédigé pour éviter un commentaire inutile : 

Commentaires dans le code : l'exemple à suivre

Règle n°3 : un commentaire n’est pas une liste de chose à faire

Déboguer votre code est une bonne chose ! Parfois il vous faut plus de temps pour trouver le bogue que pour le corriger. Cependant, cela ne veut pas dire que vous pouvez vous permettre de seulement signaler un problème sans le corriger.

Bien entendu, lorsque vous rédiger votre code vous pouvez utiliser les commentaires pour vous indiquer ce qu’il vous reste à faire, où vous vous êtes arrêté…  Mais ces commentaires doivent disparaître avant que vous partagiez ou poussiez votre code dans le produit final.

Voici un exemple à ne pas reproduire 👇🏻

Commentaires dans le code : l'exemple à ne pas suivre

Et voici un bon exemple : 

Commentaires dans le code : l'exemple à suivre

Quand rédiger un commentaire ?

Écrire des commentaires dans votre code n’est pas une obligation, loin de là !  Vous trouverez de nombreux articles sur internet donnant les pours et contres de cette pratique. La seule chose que nous vous recommandons est d’être organisé et de les écrire judicieusement, afin d’apporter de la valeur à votre code et non pas le rendre plus compliqué.

Ajouter des commentaires : un travail d’équipe

La manière la plus efficace pour implémenter des règles sur la rédaction de commentaires dans vos codes est de définir celles-ci en vous demandant conseil à votre équipe de développement. Enfin, une fois vos règles rédigées, vous pourrez inclure une ligne à votre Définition of Done pour vous assurer que tout le monde les suit !