Les commentaires en programmation<span class="wtr-time-wrap after-title"><span class="wtr-time-number">7</span> min read</span>

Les commentaires en programmation7 min read

Les commentaires sont trop souvent négligés par les débutants. On se dit que cela ne sert à rien… et quelques mois après on en paye les conséquences.

Lesquelles ? Et bien au fur et à mesure que le temps passe après finalisation de votre programme son code est devenu incompréhensible au premier regard, il marche mais vous ne savez pas/plus ce qu’il fait. Et c’est encore pire si c’est un autre programmeur qui touche à votre code, il sera complètement perdu dans toutes ces lignes de code…

Je sais ce que c’est, je suis aussi passé par là. J’avais réalisé un site web programmé en Python ( avec Django ) dont j’était très content et sur lequel j’ai voulu retoucher au code quelques temps plus tard. il m’a fallu plusieurs jours pour faire le point sur chaque fonctionnalité du code.

Tout ces efforts inutiles et ce temps perdu venaient d’une seule erreur : je n’avais pas commenté mon code !

C’était vraiment une catastrophe, je ne comprenais pas comment mon code fonctionnait alors que je l’avait créé quelques semaines plus tôt.

C’est vrai que vu comme ça, je passe probablement pour un idiot. Qui oublie son propre code ? Et bien, beaucoup de monde !

En fait, il y a 3 choses qui rendent votre code illisible avec le temps :

  • Les technologies évoluent et vous êtes face à une vieille technologie que vous ne maîtrisez plus réellement ;
  • Vous avez réalisé votre projet il y a plusieurs semaines et vous avez oublié ce que fait tel ou tel fonction ;
  • Vous avez gagné de l’expérience et votre ancien code vous semble mauvais. Vous ne l’écririez plus du tout comme ça et il est désormais difficile à comprendre à cause de ça.

On comprend donc que notre code ne conserve pas toujours sa cohérence. Vos connaissances évoluent , vous oubliez et globalement, les choses changent. On ne peut donc pas compter sur notre mémoire pour comprendre éternellement notre code. C’est là que les commentaires entrent en jeu.

C’est quoi un commentaire ?

Un commentaire c’est une annotation permettant d’écrire dans votre fichier de code sans que la phrase soit prise en compte lors de l’exécution du programme. Par exemple :

function test() // Voici un commentaire expliquant ce que fait la fonction
{
...fait des trucs
}

Ici, on a inséré une phrase en commençant la ligne avec “//”. Ces symboles permettent d’indiquer au langage de programmation que la suite de la ligne ne doit pas être prise en compte.

Il faut bien comprendre que les commentaires ne servent qu’au programmeur. Ils n’influent jamais sur l’exécution du programme.

Comment et pourquoi est-ce que l’on écrit des commentaires ?

Nous allons maintenant voir comment est-ce que l’on écrit des commentaires. D’abord nous découvrirons quelles sont les syntaxes, puis, nous aborderons comment et à quelle occasion on écrit des commentaires.

Nous avons vu une première syntaxe permettant d’insérer des commentaires sur une ligne, celle-ci est “//”. Elle fonctionne dans tout les langages de programmation à l’exception de l’HTML. Ce dernière possède cette syntaxe : <!– votre commentaire ->

En plus des commentaires sur une seule ligne, il en existe des multi-lignes qui s’écrivent ainsi : /* votre commentaire sur plusieurs lignes */

Ici l’intérêt est de pouvoir donner plus de détails via des commentaires plus long.

La seule exception à cette syntaxe est celle du python où l’on fait “”” votre commentaire “”” à la place (notez que c’est un triple double-guillemets )

Pourquoi voulons nous commenter notre code ?

Maintenant que vous savez comment faire ( et c’est plutôt facile ), nous allons comprendre pourquoi il est nécessaire de commenter son code.

Je vous ai raconté au début de cet article les problèmes que j’ai rencontré à cause de ma mauvaise organisation et de mon absence de commentaires. Et bien croyez moi, ça vous arrivera aussi !

Les débutants ont souvent tendance à éviter totalement les commentaires. C’est long et ça semble totalement inutile, c’est vrai, pourquoi expliquer quelque chose que j’ai crée moi-même.

Voici les principales raisons ( il en existe des centaines) qui font qu’il est essentiel de commenter votre code :

  • Parfois on a simplement besoin de connaître l’utilité d’une fonction sans avoir à la lire ;
  • On a tendance à oublier l’utilité d’une fonction ou d’une méthode avec le temps ;
  • Il est beaucoup plus simple de lire un code commenté. Donc, si vous devez communiquer votre code à quelqu’un, vous lui simplifiez la vie ;
  • Commenter le code permet de directement cibler les fonctions à modifier si vous voulez changer votre application.

Que vous soyez freelance ou que vous travailliez en équipe, il donc est inconcevable que vous ne commentiez pas votre travail afin que les autres programmeurs ou vous-même puissent le comprendre par la suite. Rien que pour cette raison, commentez votre code dès maintenant !

Malheureusement , le faire ne suffit pas si ce n’est pas optimisé. Nous allons donc voir les conventions de commentaires et les erreurs à ne pas faire.

Conventions et erreurs à éviter

Les choses que l’on commente le plus en programmation ce sont les fonctions. Qu’elles soient isolées ou dans une classe, il est essentiel de les commenter.

Lorsqu’on le fait, on doit expliquer non pas ce que la fonction fait, mais son résultat. Par exemple :

// renvoie true ou false si age (nombre > 0) est supérieur ou inférieur à 18 
function calculeragemajeur(age)
{
    if (age >= 18)
          {
              return true
           }
    return false
}

Ici on explique tout alors qu’on peut simplifier comme ceci :

// vérifie si age - nombre est majeur ou non
function calculeragemajeur(age)
{
    if (age >= 18)
          {
              return true
           }
    return false
}

C’est plus simple non ? Vous devez essayer de simplifier au maximum vos commentaires tout en les rendant facilement compréhensibles.

En plus de simplifier et d’être concis, vous devez indiquer le type de la variable passée si vous êtes sur un langage non typé. Ceci va vous permettre d’utiliser facilement ces fonctions et de permettre aux autres programmeurs de comprendre directement la fonction et ses variables.

Les erreurs à éviter

Les programmeurs qui commencent à commenter leur code tombent souvent dans l’extrême. Au lieu de ne jamais commenter, ils expliquent chaque ligne de code. On obtient alors un résultat opposé au but recherché : au lieu de synthétiser le code, on le complexifie en ajoutant du texte inutile.

Vous devriez toujours commenter les fonctions depuis l’extérieur. Ne commentez jamais une seule ligne de code, commentez un groupe de ligne de code exécutant une certaine action.

En conclusion

Les commentaires sont essentiels si vous voulez avoir un code propre et lisible. Sans ça , vous allez forcément avoir des problèmes dans les mois à venir.

Vous devriez commencer dès aujourd’hui. Essayez de synthétiser le fonctionnement d’un groupe de lignes de code ou d’une fonction. Ne tombez pas dans l’extrême en commentant chaque ligne de code. Expliquez clairement les actions effectués par votre code.

J’espère que cet article vous aura permis de comprendre le fonctionnement des commentaires et leur intérêt.

Si cet article vous as plu, vous pouvez vous abonner à ma newsletter pour recevoir le guide GRATUIT Ultime pour bien débuter la programmation

Vous abonner à notre newsletter

* champ requis



Je vous remercie d’avoir lu cet article, au plaisir de vous revoir sur mon blog !

Laisser un commentaire

Fermer le menu
×
×

Panier