0176215544 contact@ouicom.fr

Comment commenter correctement son code et pourquoi est-ce important?

ON SAIT LE FAIRE

Tout d’abord, il faut comprendre que chaque développeur à sa propre façon de coder. Ainsi, la lecture du code est personnelle. En effet, les développeurs ont leur propre logique de nommer des « classes », des « id » et surtout ils ont des façons de raisonner différente. Chaque développeur pense donc que son code est lisible par d’autres mais ce n’est pas forcément le cas. C’est pourquoi il est impératif de commenter son code afin que celui-ci puisse être repris et lu par d’autres développeurs. Le code sera donc clair lisible et compréhensible.

Comment bien commenter son code ?

Tout d’abord qu’est ce qu’un commentaire ?

Un commentaire est une indication, une parenthèse ou une volonté du développeur d’expliquer le code qu’il a écrit. Dans un fichier CSS :

/** Style body **/

body{

background-color:#ffffff;

}

h1{
color:#000000;
}

Il existe plusieurs façons d’écrire un commentaire selon le type de fichier codé. Par exemple, nous ne commentons pas de la même manière dans un fichier CSS et dans un fichier HTML.

Par exemple:

CSS

/** Style body **/

body{

background-color:#ffffff;

}

h1{
color:#000000;
}

HTML

<!-- Ceci est un paragraphe-->

 Je suis un paragraphe 

Pour commenter correctement un code, il faut suivre 3 principes :

  • être le plus concis possible,
  • être pertinent,
  • les utiliser mais pas à outrance.

Certains penseront que de commenter son code doit être rare, mais dans ce cas-là, le code doit parfaitement être transparent et les conventions d’appellation explicite. 

Les Commentaires d’en-tête

Lorsque vous ouvrez un fichier, le code ne commence pas immédiatement. Le ficher débute par un texte en commentaire. Généralement, ce commentaire décrit le but, les dépendances, les fonctions, les variables … que l’on peut trouver dans ce fichier. Cette méthode est un peu obsolète.

La meilleure méthode est de créer un fichier de documentation externe car sinon, à chaque modification, vous devrez modifier votre commentaire et votre documentation, qui doit être faite pour tout projet.

Les commentaires d’en tête ont pour fonction en général de donner des explications sur ce que l’on va trouver par la suite.

Par exemple

/**  Le site de Jean Dupont.
	* @author
	* @version 1.0
*/

Ici on apprend que c’est le site de Jean Dupont, l’auteur et la version du site.

Les Commentaires in-line

Les commentaires de code source le plus courant sont les commentaires in-line.

Il faut être prudent avec ce type de commentaires car, effectivement on peut rapidement en abuser et rendre son code extrêmement lourd et finalement incompréhensible. Mais il ne faut pas non plus être économe sur ces commentaires car ils permettent quand même d’expliquer. Il faut trouver le bon équilibre qui s’acquiert avec le temps.

Généralement, pour décrire le code une simple ligne de commentaire au-dessus du code suffit :

 // Verifie s'il y a un commentaire. Si oui, envoi d’un message de remerciement
function commentaireCode () {
  var commentaire = document.getElementbyID("commentaire_code").value; 
  if (comment != null && comment != '') { 
        return console.log("Merci pour votre commentaire")
}

Aussi les commentaires servent à aider vos collaborateurs. Vous pouvez par exemple, les avertir que vous avez essayé un code mais qu’il ne fonctionne pas. De faire attention à certaines fonctions etc…

NOTRE CONCLUSION 

Pour plus de clartés et de compréhensions pour vous et vos collaborateurs, il ne faut pas hésiter à commenter votre code. Attention à ne pas en abuser et surtout que ces commentaires aient un but utile pour vous et les développeurs qui pourraient le lire. Cela permettra un suivi de votre projet plus encadré. 

Share This