Les commentaires

Jusqu'à présent, nous avions des programmes courts et n'ayant qu'une seule fonction. Il ne fallait pas forcément expliquer le code. A partir de maintenant, il va falloir s'efforcer de mettre des commentaires pour expliquer comment fonctionne le code. Les commentaires vont permettre de rajouter des précisions. C'est du texte en langage humain, qui n'est destiné qu'aux programmeurs. On y met ce que l'on veut et lors de la compilation tout ce qui est commentaire va disparaître. Mettre ou pas des commentaires ne va donc pas changer le code final, ni sa vitesse d'exécution.

Les commentaires sont importants si vous donnez votre code à lire à une tierce personne, mais aussi pour vous qui risquez de relire votre code dans quelques temps.

Un programme bien commenté va donc indiquer clairement ce que l'on a voulu faire, et si vous demandez de l'aide, cela permet de ne pas décourager ceux qui voudraient répondre. Des fois le commentaire est en contradiction avec le code. Si on n'a que le code on ne peut pas toujours savoir ce que la personne veut faire:

delay(10); // Attente 10s

Avec un tel commentaire, je vois une grosse erreur, ce n'est pas 10s qui est codé mais 10ms. Sans le commentaire, je risque de ne rien voir.

Noms des variables

Ce problème a déjà été abordé, c'est un petit rappel. Les noms que vous allez choisir pour les variables, les fonctions, et de façon générale de toutes les entités du C, sont déjà des commentaires si vous faites bien les choses. On peut alors ne pas rajouter de commentaires en plus. Si votre variable s'appelle abscisse c'est suffisamment clair pour ne pas avoir à expliquer davantage.

// en fin de ligne

C'est un commentaire de ligne, après le double "barre oblique qui monte vers la droite" (double slash pour les moins puristes), tout ce qui est derrière est ignoré à la compilation. C'est donc le début d'un commentaire.

Un commentaire doit être utile, sinon il ne sert à rien. En conséquence il faut éviter les traductions C -> français:

delay(1000); // Attendre 1s

On voit bien que c'est une attente d'une seconde, c'est dans l'instruction (peut être pas les premières fois que vous voyez cette instruction). Il vaut mieux ne rien mettre que de mettre le commentaire ci-dessus. Si on veut mettre quelque chose, on peut essayer de se poser la question non pas "Que fait cette instruction?" mais "A quoi sert cette instruction? Pourquoi cela ne fonctionnerait pas si elle n'y était pas?". Cela peut donner:

delay(1000); // Lire la valeur affichée

// sur plusieurs lignes

Parfois les commentaires sont trop longs pour tenir sur une seule ligne. On va alors à la ligne suivante et on doit remettre les //.

Si on met des commentaires sur la même ligne qu'une instruction, cela commente en principe que la ligne concernée, éventuellement la ligne d'en dessous. Mais si on veut mettre un commentaire sur plusieurs lignes, on peut alors mettre le commentaire seul sur une ligne, comme on le ferait pour un titre.

Une ligne vide est aussi un commentaire. Séparer des ensembles d'instructions par une ligne vide indique que l'ensemble des instructions a une fonction globale.

On peut aussi mettre des titres de différents niveaux (titre, sous titre, sous sous titre...) en encadrant différemment des titres:

//####################################
//####################################
//####                           #####
//####   Grand titre important   ##### 
//####                           #####
//####################################
//####################################

...

//####################################
//##     Titre moins important     ### 
//####################################

...

//########## Petit titre #############

...

// ------ Tout petit titre -----------

Enfin, souvent en début de programme, On utilise les premières lignes pour y mettre des information supplémentaires: version, date, auteur, nom du fichier, utilisation, licence...

/* commentaire */

Il existe aussi des commentaires blocs. Tout ce qui est entre /* et */ est ignoré par le compilateur. /* indique "début de commentaire" et */ "fin de commentaire". Ce type de commentaire peut donc couvrir plusieurs lignes mais on ne peut pas l'imbriquer (mettre un couple /* */ à l'intérieur d'un couple /* */ comme on le ferait avec des parenthèses ou des accolades). On trouve souvent ce type de commentaire en début de programme, ou pour désactiver momentanément plusieurs lignes de code pendant une phase de mise au point.