Programmation/Commentaires

Un livre de Wikilivres.
Sauter à la navigation Sauter à la recherche
Ébauche

Cette page est considérée comme une ébauche à compléter. Si vous possédez quelques connaissances sur le sujet, vous pouvez les partager en éditant dès à présent cette page (en cliquant sur le lien « modifier »).

Ressources suggérées : Aucune (vous pouvez indiquer les ressources que vous suggérez qui pourraient aider d'autres personnes à compléter cette page dans le paramètre « ressources » du modèle? engendrant ce cadre)


Un commentaire est un texte ajouté au code source d'un programme servant à décrire le code source, facilitant sa compréhension par les humains. Il est donc séparé du reste du code grâce à une syntaxe particulière, ce qui fait qu'en général, le commentaire est ignoré par le compilateur? ou l'interpréteur? du langage concerné.

Pourquoi ajouter des commentaires ?[modifier | modifier le wikicode]

Ajouter des commentaires à un programme permet de décrire ce que fait le code, en utilisant un langage naturel. Il est important d'ajouter des commentaires pour les raisons suivantes :

Expliquer le rôle d'une fonction
Utiliser une fonction est compliqué si on ne sait pas ce qu'elle fait, ce qu'elle retourne. Une explication permet de savoir comment l'utiliser.
Expliquer le fonctionnement d'un algorithme complexe
Le code source des algorithmes les plus complexes ne suffit pas à en comprendre le fonctionnement. Une description synthétique permet de le modifier pour l'adapter à un autre projet, ou pour le corriger en cas de problèmes.
Justifier certains choix techniques
Un code source est souvent repris ultérieurement (correction, réutilisation). Si certains choix ne sont pas justifiés par un commentaire explicatif, ils pourront être remis en cause par le développeur.


Syntaxe[modifier | modifier le wikicode]

La syntaxe utilisée dépend du langage de programmation, ou du format de données. Dans les exemples qui suivent, l’élément de syntaxe caractéristique du commentaire est en vert. Lorsqu'il n'est pas présent à la fin du commentaire, il se termine implicitement à la fin de la ligne de code :

<!-- Un commentaire ici -->
/* Un commentaire ici */
// Un commentaire ici
  • Basic, Batch (pour DOS) :
REM Un commentaire ici
# Un commentaire ici
-- Un commentaire ici
{ Un commentaire ici }

ou

(* Un commentaire ici *)

Autre utilisation[modifier | modifier le wikicode]

Certains langages utilisent une syntaxe particulière de commentaires interprétée par une ligne de commande spéciale pour générer une documentation :

  • Java : La documentation générée est au format HTML, utilisant la syntaxe suivante :
/** Décrire ici la classe ou la méthode
   dont la déclaration suit ce commentaire
   en utilisant la syntaxe HTML
   @tag valeur
*/
  • C# : La documentation générée est au format XML, utilisant l'une des deux syntaxes suivantes :
/** Décrire ici la classe ou la méthode
   dont la déclaration suit ce commentaire
   <tag>valeur</tag>
*/
/// Décrire ici la classe ou la méthode
/// dont la déclaration suit ce commentaire
/// <tag>valeur</tag>