# Commentaire (informatique)

Les commentaires sont, en programmation informatique, des portions du code source ignorées par le compilateur ou l’interpréteur, car destinées en général à un lecteur humain et non censées influencer l’exécution du programme.
Les commentaires sont le plus souvent utilisés pour expliquer le code ; certains outils, appelés générateurs de documentation, permettent d’extraire l’information disponible dans les commentaires pour créer automatiquement une documentation du programme.
On utilise parfois une mise en commentaires pour court-circuiter quelque temps une section de code, mais aussi pour préciser des contraintes ou des propriétés, notamment des préconditions, des postconditions et des invariants comme cela se fait dans la programmation par contrat.

## Types de commentaires

Les façons de distinguer les commentaires du reste du code varient suivant le langage utilisé. On distingue trois catégories principales, chaque langage pouvant implémenter plusieurs catégories de commentaires :
* commentaires en pleine ligne ;
* commentaires de fin de ligne ;
* commentaires en bloc.

### Commentaires en pleine ligne

Un commentaire en pleine ligne commence par un marqueur annonçant une ligne de commentaires (ou par l’absence d’un marqueur annonçant une ligne de code). BASIC, Fortran et Cobol sont des langages utilisant des commentaires en pleine ligne. Le code reprend naturellement à la ligne suivante.
* BASIC :
    REM commentaire
* Cobol :
    000010*COMMENTAIRE
    (l’astérisque doit se trouver en 7e position sur la ligne)
* Fortran :
    C commentaire
    (exactement 6 espaces entre le caractère C et le commentaire ; C doit absolument être le premier caractère de la ligne)
* REALbasic :
    rem commentaire
    // commentaire
    ' commentaire
* Les fichiers de commandes BATCH pour cmd.exe de Windows :
    rem commentaire

### Commentaires de fin de ligne

Un commentaire de fin de ligne commence par un marqueur annonçant le début d’un commentaire, et se termine automatiquement à la fin de la ligne, sans nécessité de marqueur de fin. Les langages C++ et Java utilisent ce type de commentaires.
* Ada, AppleScript, Lua, Lingo, Haskell, Transact-SQL :
    --commentaire
* APL
    ⍝(symbole "lampe". Attention, c'est de l'Unicode)
* Assembleur :
    ; commentaire
* BASIC :
    REM commentaire (après un « : » dans QBasic)
    ' commentaire
* C (C99), C++, C#, D, Delphi, Java, JavaScript, PHP, Scilab :
    // commentaire
* DCL :
    $! commentaire
* Fortran 90 :
    ! commentaire
* mySQL :
    --commentaire
    #commentaire
* Perl, Python, R, Ruby, C shell, Bourne shell, Tcl, et autres langages shell :
    # commentaire
* PHP :
    # commentaire
    // commentaire
* PILOT :
    R:commentaire
    (une lettre de commande peut débuter immédiatement après le commentaire, sur la même ligne)
* TeX, LaTeX, PostScript, Matlab :
    % commentaire
* Texinfo :
    @c commentaire
    @comment commentaire
* Visual Basic, StarOffice Basic :
    ' commentaire
* REALbasic :
    ' commentaire
    // commentaire
* VHDL :
    -- commentaire

### Commentaires en bloc

Un commentaire en bloc commence par un marqueur annonçant le début d’un commentaire et se termine avec un marqueur annonçant sa fin, leur intérêt principal est de pouvoir mettre en commentaire plusieurs lignes sans éditer chacune d'entre elles. Quelques exemples :
* AppleScript, Modula-2, Modula-3, Oberon, Pascal et Caml:
    (* commentaire *)
* C, C++, C#, CSS, Java, JavaScript, PHP et PL/I :
    /* commentaire */
* Delphi :
    (* commentaire *)
    { commentaire }
* Haskell :
    {- commentaire -}
* Lua :
    --[[ commentaire ]]
* MediaWiki, SGML, HTML, XML :
    <!-- commentaire -->
* Python :
    Python n'a pas de commentaire en bloc à proprement parler, mais les chaînes de caractères constituant à elles-seules une instruction peuvent jouer ce rôle, pour éventuellement servir de docstring: """ commentaire """ ou ''' commentaire '''

### Commentaires de fin de fichier

Un commentaire de fin de fichier commence par un marqueur annonçant que tout ce qui suit, jusqu’à la fin du fichier, doit être considéré comme un commentaire. ATS est un exemple de langage utilisant ce type de commentaires.
* ATS :
    //// commentaire
* Tcl :
    Grâce à un caractère de contrôle: ^Z

### Commentaires intégrés sans marqueurs

En Brainfuck tous les caractères sauf + -<>,. sont ignorés et considérés comme des commentaires.

## Utilisation des commentaires
### Documentation

Des outils comme Doxygen, Javadoc ou RDoc permettent de structurer les commentaires présents dans le code et de créer une documentation complète. Celle-ci est la plupart du temps destinée à un programmeur désirant développer avec une bibliothèque, mais il est tout à fait possible d’utiliser cette méthode pour écrire la documentation destinée à l’utilisateur final.
(un extrait de la documentation javadoc de Sun Microsystems ; le commentaire est dans un format compréhensible par le processeur javadoc)

### Désactivation de code

On utilise souvent les commentaires pour cacher rapidement des portions de code au compilateur ou à l’interpréteur, par exemple pour tester des implémentations alternatives, ou pour désactiver temporairement des fonctionnalités.
Cette désactivation est la plus facile à effectuer lorsque le langage permet des commentaires par blocs. Cependant, dans le cas où la portion de code à cacher contient déjà des commentaires, la syntaxe du langage ne permet pas toujours simplement d’imbriquer ces commentaires. Certains langages fournissent un niveau supérieur de commentaires pour pallier cela :
* Préprocesseur C/C++:
    #if 0
    code; //commentaire
    encore du code; /* commentaire */
    #endif
* XML :
    <![IGNORE[
    <code> <!-- commentaire --> </code>

#### Astuce du code facilement (dé)commentable

* en C (C99), C++, C#, Java, JavaScript, PHP :
    Mon code
Pour le décommenter, il suffit de retirer la 1re étoile *.
Pour alterner entre deux blocs de code en C (C99), C++, C#, Java, JavaScript, PHP :
    /* --- */ // 1er bloc actif
    Code version 1
    Code version 2
Pour activer le second bloc, il suffit d'ajouter un espace entre l'étoile et le slash de la première ligne :
    /* --- * / // 2ème bloc actif
    Code version 1
    Code version 2
Cependant l'utilisation des commentaires de bloc pour commenter une partie du code n'est pas compatible avec du code contenant des blocs de commentaires car ils ne peuvent pas être imbriqués. L'utilisation des commentaires de fin de ligne, qui n'a pas ce problème, est la solution utilisée par la plupart des éditeurs de code source.

## Exemples
### C

(extrait du fichier fork.c du noyau Linux)

### Perl

(extrait de perlbug.PL dans la distribution standard de Perl)

### PHP

(extrait de MediaWiki, le logiciel utilisé par Wikipedia)