Programmation/Commentaires

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é.

Abstraction

Instructions

Pourquoi ajouter des commentaires ?

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.
Lister les contextes d'appel à une fonction: Un commentaire expliquant quand la fonction est appelée permet de comprendre son rôle et les circonstances de déclenchement de l'appel à la fonction.

Selon Martin Fowler, l'ajout de commentaire peut aussi être le symptôme d'un code de mauvaise qualité^[1], notamment parce qu'il ne ferait pas appel à des fonctions bien découpées et bien nommées.

Syntaxe

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.

Bloc de commentaire

Un bloc de commentaire commence par une séquence de caractères (en vert ci-dessous), et se termine par une autre séquence. Le commentaire peut donc s'étaler sur plusieurs lignes.

XML, SGML, XHTML, HTML :

<!-- Un commentaire ici -->

CSS, C, Java, C++, C#, JavaScript, PHP :

/* Un commentaire ici */

Pascal :

{ Un commentaire ici }

ou

(* Un commentaire ici *)

Ligne de commentaire

Une ligne de commentaire commence par une séquence de caractères (en vert ci-dessous), et se termine implicitement à la fin de la ligne de code. Si le commentaire s'étale sur plusieurs lignes, il faut répéter la séquence au début de chaque ligne.

Java, C++, C#, JavaScript, PHP :

// Un commentaire ici

Basic, Batch (pour DOS) :

REM Un commentaire ici

Shell unix, PHP, Python, fichier de configuration (.ini, .cfg) :

# Un commentaire ici

Fichier de configuration (.ini, .cfg) :

; Un commentaire ici

Ada, ASN.1, Eiffel :

-- Un commentaire ici

Autre utilisation

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>

PHP :

La phpdoc est interprétée pour générer une documentation automatique, par les IDE pour l'autocomplétion, et par les analyseurs de code statique chargés de garantir la qualité du code. Elle se distingue des commentaires de base par l'ajout d'une deuxième étoile au début d'un commentaire de bloc, puis d'un arobase avant le mot clé :

    /** @var int|null */
    private $id;

Références

↑ https://github.com/lee-dohm/code-smells#comments

[1] ttps://github.com/lee-dohm/code-smells#comments

[1]