Commentaire (programmation informatique) - Comment (computer programming)

Pour les commentaires dans le balisage Wikipedia, voir Help:Wiki markup#Character formatting et WP:COMMENT .
Une illustration du code source Java avec les commentaires du prologue indiqués en rouge et les commentaires en ligne en vert . Le code du programme est en bleu .

En programmation informatique , un commentaire est une explication ou une annotation lisible par un programmeur dans le code source d'un programme informatique . Ils sont ajoutés dans le but de rendre le code source plus facile à comprendre pour les humains, et sont généralement ignorés par les compilateurs et les interprètes . La syntaxe des commentaires dans divers langages de programmation varie considérablement.

Les commentaires sont parfois également traités de diverses manières pour générer une documentation externe au code source lui-même par des générateurs de documentation , ou utilisés pour l'intégration avec des systèmes de gestion de code source et d'autres types d' outils de programmation externes .

La flexibilité fournie par les commentaires permet un large degré de variabilité, mais les conventions formelles pour leur utilisation font généralement partie des guides de style de programmation.

Aperçu

Les commentaires sont généralement formatés sous forme de commentaires de bloc (également appelés commentaires de prologue ou commentaires de flux ) ou de commentaires de ligne (également appelés commentaires en ligne ).

Les commentaires de bloc délimitent une région du code source qui peut s'étendre sur plusieurs lignes ou une partie d'une seule ligne. Cette région est spécifiée avec un délimiteur de début et un délimiteur de fin . Certains langages de programmation (tels que MATLAB ) permettent d'imbriquer les commentaires de bloc de manière récursive les uns dans les autres, mais d'autres (tels que Java ) ne le font pas.

Les commentaires de ligne commencent par un délimiteur de commentaire et se poursuivent jusqu'à la fin de la ligne, ou dans certains cas, commencent à une colonne spécifique (décalage de ligne de caractère) dans le code source et se poursuivent jusqu'à la fin de la ligne.

Certains langages de programmation utilisent à la fois des commentaires de bloc et de ligne avec des délimiteurs de commentaires différents. Par exemple, C++ a des commentaires de bloc délimités par /*et */qui peuvent s'étendre sur plusieurs lignes et des commentaires de ligne délimités par //. Les autres langues ne prennent en charge qu'un seul type de commentaire. Par exemple, les commentaires Ada sont des commentaires de ligne : ils commencent par --et continuent jusqu'à la fin de la ligne.

Les usages

La meilleure façon d'utiliser les commentaires est sujette à controverse ; différents commentateurs ont offert des points de vue variés et parfois opposés. Il existe de nombreuses manières différentes d'écrire des commentaires et de nombreux commentateurs offrent des conseils contradictoires.

Planification et révision

Les commentaires peuvent être utilisés comme une forme de pseudocode pour décrire l'intention avant d'écrire le code réel. Dans ce cas, il doit expliquer la logique derrière le code plutôt que le code lui-même. . 

/* loop backwards through all elements returned by the server 
(they should be processed chronologically)*/
for (i = (numElementsReturned - 1); i >= 0; i--) {
    /* process each element's data */
    updatePattern(i, returnedElements[i]);
}

Si ce type de commentaire est laissé, il simplifie le processus de révision en permettant une comparaison directe du code avec les résultats escomptés. Une erreur logique courante est que le code qui est facile à comprendre fait ce qu'il est censé faire.

Description des codes

Les commentaires peuvent être utilisés pour résumer le code ou pour expliquer l'intention du programmeur. Selon cette école de pensée, la reformulation du code en anglais simple est considérée comme superflue ; le besoin de ré-expliquer le code peut être un signe qu'il est trop complexe et doit être réécrit, ou que le nom est mauvais.

"Ne documentez pas le mauvais code - réécrivez-le."
"Les bons commentaires ne répètent pas le code ou ne l'expliquent pas. Ils clarifient son intention. Les commentaires doivent expliquer, à un niveau d'abstraction plus élevé que le code, ce que vous essayez de faire."

Les commentaires peuvent également être utilisés pour expliquer pourquoi un bloc de code ne semble pas correspondre aux conventions ou aux meilleures pratiques. Cela est particulièrement vrai pour les projets impliquant très peu de temps de développement ou de correction de bogues. Par exemple: 

' Second variable dim because of server errors produced when reuse form data. No
' documentation available on server behavior issue, so just coding around it.
vtx = server.mappath("local settings")

Description algorithmique

Parfois, le code source contient une solution nouvelle ou remarquable à un problème spécifique. Dans de tels cas, les commentaires peuvent contenir une explication de la méthodologie. Ces explications peuvent inclure des diagrammes et des preuves mathématiques formelles. Cela peut constituer une explication du code, plutôt qu'une clarification de son intention ; mais d'autres chargés de maintenir la base de code peuvent trouver une telle explication cruciale. Cela peut être particulièrement vrai dans le cas de domaines problématiques hautement spécialisés ; ou des optimisations, des constructions ou des appels de fonction rarement utilisés.

Par exemple, un programmeur peut ajouter un commentaire pour expliquer pourquoi un tri par insertion a été choisi au lieu d'un tri rapide , car le premier est, en théorie, plus lent que le second. Cela pourrait s'écrire comme suit : 

 list = [f (b), f (b), f (c), f (d), f (a), ...];
 // Need a stable sort. Besides, the performance really does not matter.
 insertion_sort (list);

Inclusion de ressources

Des logos , des diagrammes et des organigrammes constitués de constructions artistiques ASCII peuvent être insérés dans le code source formaté sous forme de commentaire. De plus, les avis de droits d'auteur peuvent être intégrés dans le code source sous forme de commentaires. Les données binaires peuvent également être codées dans les commentaires via un processus connu sous le nom de codage binaire en texte , bien qu'une telle pratique soit rare et généralement reléguée aux fichiers de ressources externes.

Le fragment de code suivant est un simple diagramme ASCII illustrant le flux de processus d'un script d' administration système contenu dans un fichier de script Windows exécuté sous Windows Script Host . Bien qu'une section marquant le code apparaisse sous forme de commentaire, le diagramme lui-même apparaît en fait dans une section XML CDATA , qui est techniquement considérée comme distincte des commentaires, mais peut servir à des fins similaires. 

<!-- begin: wsf_resource_nodes -->
<resource id="ProcessDiagram000">
<![CDATA[
 HostApp (Main_process)
    |
    V
script.wsf (app_cmd) --> ClientApp (async_run, batch_process)
                |
                |
                V
         mru.ini (mru_history)  
]]>
</resource>

Bien que ce diagramme identique aurait facilement pu être inclus en tant que commentaire, l'exemple illustre un cas où un programmeur peut choisir de ne pas utiliser de commentaires comme moyen d'inclure des ressources dans le code source.

Métadonnées

Article principal : Métadonnées

Les commentaires dans un programme informatique stockent souvent des métadonnées sur un fichier de programme.

En particulier, de nombreux mainteneurs de logiciels mettent des directives de soumission dans les commentaires pour aider les personnes qui lisent le code source de ce programme à envoyer toutes les améliorations qu'elles apportent au mainteneur.

Les autres métadonnées incluent : le nom du créateur de la version originale du fichier programme et la date à laquelle la première version a été créée, le nom du mainteneur actuel du programme, les noms des autres personnes qui ont édité le fichier programme jusqu'à présent , l'URL de la documentation sur la façon d'utiliser le programme, le nom de la licence du logiciel pour ce fichier de programme, etc.

Lorsqu'un algorithme dans une section du programme est basé sur une description dans un livre ou une autre référence, les commentaires peuvent être utilisés pour donner le numéro de page et le titre du livre ou de la demande de commentaires ou d'une autre référence.

Débogage

Une pratique courante des développeurs consiste à commenter un extrait de code, c'est-à-dire à ajouter une syntaxe de commentaire faisant de ce bloc de code un commentaire, afin qu'il ne soit pas exécuté dans le programme final. Cela peut être fait pour exclure certains morceaux de code du programme final, ou (plus communément) cela peut être utilisé pour trouver la source d'une erreur. En commentant et en exécutant systématiquement des parties du programme, la source d'une erreur peut être déterminée, ce qui permet de la corriger.

Un exemple de commentaire de code à des fins d'exclusion est ci-dessous :

Le fragment de code ci-dessus suggère que le programmeur a choisi de désactiver l'option de débogage pour une raison quelconque.

De nombreux IDE permettent d'ajouter ou de supprimer rapidement de tels commentaires avec des options de menu unique ou des combinaisons de touches. Le programmeur n'a qu'à marquer la partie du texte qu'il souhaite (dé)commenter et choisir l'option appropriée.

Génération automatique de documentation

Article détaillé : Générateur de documentation

Les outils de programmation stockent parfois la documentation et les métadonnées dans les commentaires. Celles-ci peuvent inclure des positions d'insertion pour l'inclusion automatique du fichier d'en-tête, des commandes pour définir le mode de coloration syntaxique du fichier ou le numéro de révision du fichier . Ces commentaires de contrôle fonctionnel sont aussi communément appelés annotations . Conserver la documentation dans les commentaires du code source est considéré comme un moyen de simplifier le processus de documentation, ainsi que d'augmenter les chances que la documentation soit tenue à jour avec les modifications apportées au code.

Des exemples de générateurs de documentation incluent les programmes Javadoc à utiliser avec Java , Ddoc pour D , Doxygen pour C , C++ , Java, IDL , Visual Expert pour PL/SQL , Transact-SQL , PowerBuilder et PHPDoc pour PHP . Les formes de docstring sont prises en charge par Python , Lisp , Elixir et Clojure .

C# , F# et Visual Basic .NET implémentent une fonctionnalité similaire appelée "Commentaires XML" qui sont lus par IntelliSense à partir de l' assembly .NET compilé .

Extension de syntaxe

Parfois, des éléments de syntaxe qui étaient à l'origine destinés à être des commentaires sont réutilisés pour transmettre des informations supplémentaires à un programme, telles que des « commentaires conditionnels ». De tels "commentaires chauds" peuvent être la seule solution pratique qui maintient la compatibilité descendante, mais sont largement considérés comme un bobard .

Utilisations de la directive

Il y a des cas où les caractères de commentaire normaux sont cooptés pour créer une directive spéciale pour un éditeur ou un interprète.

Deux exemples de cette direction d'un interprète sont :

  • Le « shebang » Unix – #!– utilisé sur la première ligne d'un script pour pointer vers l'interpréteur à utiliser.
  • "Commentaires magiques" identifiant l'encodage utilisé par un fichier source, par exemple le PEP 263 de Python.

Le script ci-dessous pour un système de type Unix montre ces deux utilisations : 

#!/usr/bin/env python3
# -*- coding: UTF-8 -*-
print("Testing")

Un peu similaire est l'utilisation de commentaires en C pour communiquer à un compilateur qu'un "fallthrough" par défaut dans une instruction case a été fait délibérément : 

switch (command) {
    case CMD_SHOW_HELP_AND_EXIT:
      do_show_help();
      /* Fall thru */
    case CMD_EXIT:
      do_exit();
      break;
    case CMD_OTHER:
      do_other();
      break;
    /* ... etc. ... */
  }

L'insertion d'un tel /* Fall thru */commentaire pour les lecteurs humains était déjà une convention courante, mais en 2017, le compilateur gcc a commencé à les rechercher (ou d'autres indications d'intention délibérée) et, s'il n'est pas trouvé, à émettre : « avertissement : cette déclaration peut échouer » .

De nombreux éditeurs et IDE liront des commentaires spécialement formatés. Par exemple, la fonctionnalité "modeline" de Vim ; ce qui modifierait sa gestion des onglets lors de l'édition d'une source avec ce commentaire inclus en haut du fichier : 

# vim: tabstop=8 expandtab shiftwidth=4 softtabstop=4

Soulagement du stress

Parfois, les programmeurs ajoutent des commentaires pour soulager le stress en commentant les outils de développement, les concurrents, les employeurs, les conditions de travail ou la qualité du code lui-même. L'occurrence de ce phénomène peut être facilement constatée à partir des ressources en ligne qui suivent le blasphème dans le code source.

Vues normatives

Il existe divers points de vue normatifs et opinions de longue date concernant l'utilisation appropriée des commentaires dans le code source. Certains d'entre eux sont informels et basés sur des préférences personnelles, tandis que d'autres sont publiés ou promulgués en tant que directives formelles pour une communauté particulière.

Besoin de commentaires

Les experts ont des points de vue différents sur la question de savoir si et quand les commentaires sont appropriés dans le code source. Certains affirment que le code source doit être écrit avec peu de commentaires, en partant du principe que le code source doit être auto-explicatif ou auto-documenté . D'autres suggèrent que le code devrait être abondamment commenté (il n'est pas rare que plus de 50 % des caractères autres que des espaces blancs dans le code source soient contenus dans les commentaires).

Entre ces points de vue se trouve l'affirmation selon laquelle les commentaires ne sont ni bénéfiques ni nuisibles en eux-mêmes, et ce qui compte, c'est qu'ils soient corrects et synchronisés avec le code source, et omis s'ils sont superflus, excessifs, difficiles à maintenir ou autrement inutiles.

Les commentaires sont parfois utilisés pour documenter les contrats dans l' approche de conception par contrat de la programmation.

Niveau de détail

Selon le public visé par le code et d'autres considérations, le niveau de détail et de description peut varier considérablement.

Par exemple, le commentaire Java suivant conviendrait dans un texte d'introduction conçu pour enseigner la programmation débutante : 

String s = "Wikipedia"; /* Assigns the value "Wikipedia" to the variable s. */

Ce niveau de détail, cependant, ne serait pas approprié dans le contexte du code de production, ou d'autres situations impliquant des développeurs expérimentés. De telles descriptions rudimentaires sont incompatibles avec la directive : « Bons commentaires... clarifient l'intention ». De plus, pour les environnements de codage professionnels, le niveau de détail est généralement bien défini pour répondre à une exigence de performance spécifique définie par les opérations commerciales.

modes

Il existe de nombreuses alternatives stylistiques disponibles lors de l'examen de la façon dont les commentaires doivent apparaître dans le code source. Pour les projets plus importants impliquant une équipe de développeurs, les styles de commentaires sont soit convenus avant le démarrage d'un projet, soit évoluent en fonction des conventions ou des besoins au fur et à mesure que le projet grandit. Habituellement, les programmeurs préfèrent des styles cohérents, non obstructifs, faciles à modifier et difficiles à casser.

Bloquer le commentaire

Les fragments de code suivants en C ne montrent qu'un petit exemple de la façon dont les commentaires peuvent varier d'un point de vue stylistique, tout en transmettant les mêmes informations de base : 

/*
     This is the comment body.
     Variation One.
*/

/***************************\
*                           *
* This is the comment body. *
* Variation Two.            *
*                           *
\***************************/

Des facteurs tels que les préférences personnelles, la flexibilité des outils de programmation et d'autres considérations ont tendance à influencer les variantes stylistiques utilisées dans le code source. Par exemple, la variante deux peut être défavorisée parmi les programmeurs qui ne disposent pas d' éditeurs de code source capables d'automatiser l'alignement et l'apparence visuelle du texte dans les commentaires.

Le consultant en logiciels et commentateur technologique Allen Holub est un expert qui préconise d'aligner les bords gauches des commentaires : 

 /* This is the style recommended by Holub for C and C++.
  * It is demonstrated in ''Enough Rope'', in rule 29.
  */

 /* This is another way to do it, also in C.
 ** It is easier to do in editors that do not automatically indent the second
 ** through last lines of the comment one space from the first.
 ** It is also used in Holub's book, in rule 31.
 */

L'utilisation de /* et */ comme délimiteurs de commentaire de bloc a été héritée de PL/I dans le langage de programmation B, le prédécesseur immédiat du langage de programmation C.

Commentaires de ligne

Les commentaires de ligne utilisent généralement un délimiteur arbitraire ou une séquence de jetons pour indiquer le début d'un commentaire, et un caractère de nouvelle ligne pour indiquer la fin d'un commentaire.

Dans cet exemple, tout le texte des caractères ASCII // à la fin de la ligne est ignoré. 

// -------------------------
// This is the comment body.
// -------------------------

Souvent, un tel commentaire doit commencer à l'extrême gauche et s'étendre à toute la ligne. Cependant, dans de nombreuses langues, il est également possible de mettre un commentaire en ligne avec une ligne de commande, d'y ajouter un commentaire - comme dans cet exemple Perl : 

print $s . "\n";     # Add a newline character after printing

Si un langage autorise à la fois les commentaires de ligne et les commentaires de bloc, les équipes de programmation peuvent décider d'une convention pour les utiliser différemment : par exemple, des commentaires de ligne uniquement pour les commentaires mineurs et des commentaires de bloc pour décrire des abstractions de niveau supérieur.

Mots clés

Les programmeurs peuvent utiliser des balises informelles dans les commentaires pour faciliter l'indexation des problèmes courants. Ils peuvent ensuite être recherchés à l'aide d'outils de programmation courants, tels que l' utilitaire grep Unix ou même mis en évidence par la syntaxe dans les éditeurs de texte . Ceux-ci sont parfois appelés « codetags » ou « jetons ».

Ces balises sont très différentes, mais peuvent inclure :

  • BUG – un bogue connu qui doit être corrigé.
  • FIXME – devrait être corrigé.
  • HACK – une solution de contournement.
  • À FAIRE – quelque chose à faire.
  • UNDONE - une inversion ou "roll back" du code précédent.
  • XXX - avertir les autres programmeurs d'un code problématique ou erroné

Exemples

Comparaison

Article détaillé : Comparaison des langages de programmation (syntaxe) § Commentaires

Les conventions typographiques pour spécifier les commentaires varient considérablement. De plus, les langages de programmation individuels fournissent parfois des variantes uniques. Pour un examen détaillé, veuillez consulter l' article de comparaison des langages de programmation .

Ada

Le langage de programmation Ada utilise '--' pour indiquer un commentaire jusqu'à la fin de la ligne.

Par exemple: 

  -- the air traffic controller task takes requests for takeoff and landing
   task type Controller (My_Runway: Runway_Access) is
      -- task entries for synchronous message passing
      entry Request_Takeoff (ID: in Airplane_ID; Takeoff: out Runway_Access);
      entry Request_Approach(ID: in Airplane_ID; Approach: out Runway_Access);
   end Controller;

APL

APL utilise ⍝pour indiquer un commentaire jusqu'à la fin de la ligne.

Par exemple: 

⍝ Now add the numbers:
c←a+b ⍝ addition

Dans les dialectes qui ont les primitives ⊣("left") et ⊢("right"), les commentaires peuvent souvent être à l' intérieur ou séparés des déclarations, sous la forme de chaînes ignorées : 

d←2×c ⊣'where'⊢ c←a+ 'bound'⊢ b

AppleScript

Cette section du code AppleScript montre les deux styles de commentaires utilisés dans ce langage. 

(*
This program displays a greeting.
*)
on greet(myGreeting)
     display dialog myGreeting & " world!"
end greet

-- Show the greeting
greet("Hello")

DE BASE

Dans ce fragment de code BASIC classique, le mot-clé REM ( " Remarque " ) est utilisé pour ajouter des commentaires. 

10 REM This BASIC program shows the use of the PRINT and GOTO Statements.
15 REM It fills the screen with the phrase "HELLO"
20 PRINT "HELLO"
30 GOTO 20

Dans les versions ultérieures de Microsoft BASIC, notamment Quick Basic , Q Basic , Visual Basic , Visual Basic .NET et VB Script ; et dans les descendants tels que FreeBASIC et Gambas, tout texte sur une ligne après un caractère ' (apostrophe) est également traité comme un commentaire.

Un exemple en Visual Basic .NET : 

Public Class Form1
    Private Sub Button1_Click(sender As Object, e As EventArgs) Handles Button1.Click
        ' The following code is executed when the user
        ' clicks the button in the program's window.
        rem comments still exist.

        MessageBox.Show("Hello, World") 'Show a pop-up window with a greeting
    End Sub
End Class

C

Ce fragment de code C montre l'utilisation d'un commentaire de prologue ou d'un « commentaire de bloc » pour décrire l'objectif d'une instruction conditionnelle . Le commentaire explique les termes et concepts clés et comprend une courte signature du programmeur qui a rédigé le code. 

 /*
  * Check if we are over our maximum process limit, but be sure to
  * exclude root. This is needed to make it possible for login and
  * friends to set the per-user process limit to something lower
  * than the amount of processes root is running. -- Rik
  */
 if (atomic_read(&p->user->processes) >= p->rlim[RLIMIT_NPROC].rlim_cur
     && !capable(CAP_SYS_ADMIN) && !capable(CAP_SYS_RESOURCE))
     goto bad_fork_free;

Depuis C99, il est également possible d'utiliser la syntaxe // de C++, indiquant un commentaire sur une seule ligne.

Configuration Cisco IOS et IOS-XE

Le point d'exclamation ( ! ) peut être utilisé pour marquer des commentaires dans le mode de configuration d'un routeur Cisco, mais ces commentaires ne sont pas enregistrés dans la mémoire non volatile (qui contient la configuration de démarrage), ni affichés par la commande "show run" .

Il est possible d'insérer du contenu lisible par l' homme qui fait réellement partie de la configuration et peut être enregistré dans la configuration de démarrage NVRAM via :

  • La commande "description", utilisée pour ajouter une description à la configuration d'une interface ou d'un voisin BGP
  • Le paramètre "name", pour ajouter une remarque à une route statique
  • La commande "remark" dans les listes d'accès
! Paste the text below to reroute traffic manually
config t
int gi0/2
no shut
ip route 0.0.0.0 0.0.0.0 gi0/2 name ISP2
no ip route 0.0.0.0 0.0.0.0 gi0/1 name ISP1
int gi0/1
shut
exit

Fusion froide

ColdFusion utilise des commentaires similaires aux commentaires HTML , mais au lieu de deux tirets, il en utilise trois. Ces commentaires sont capturés par le moteur ColdFusion et ne sont pas imprimés dans le navigateur. 

 <!--- This prints "Hello World" to the browser. --->
 <cfoutput>
   Hello World<br />
 </cfoutput>

Fortran IV

Ce fragment de code Fortran IV montre comment les commentaires sont utilisés dans cette langue, qui est très orientée colonnes. Une lettre "C" dans la colonne 1 fait que la ligne entière est traitée comme un commentaire. 

C
C Lines that begin with 'C' (in the first or 'comment' column) are comments
C
      WRITE (6,610)
  610 FORMAT(12H HELLO WORLD)
      END

Notez que les colonnes d'une ligne sont par ailleurs traitées comme quatre champs : 1 à 5 est le champ d'étiquette, 6 fait que la ligne est considérée comme une continuation de l'instruction précédente ; et les déclarations et déclarations vont de 7 à 72.

Fortran 90

Ce fragment de code Fortran montre comment les commentaires sont utilisés dans cette langue, les commentaires eux-mêmes décrivant les règles de formatage de base. 

!* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
!* All characters after an exclamation mark are considered as comments *
!* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
program comment_test
    print '(A)', 'Hello world' ! Fortran 90 introduced the option for inline comments.
end program

Haskell

Les commentaires de ligne en Haskell commencent par '--' (deux tirets) jusqu'à la fin de la ligne, et les commentaires sur plusieurs lignes commencent par '{-' et se terminent par '-}'. 

{- this is a comment
on more lines -}
-- and this is a comment on one line
putStrLn "Wikipedia"  -- this is another comment

Haskell fournit également une méthode de programmation alphabétisée de commentaires connue sous le nom de "Bird Style". Dans ce cas, toutes les lignes commençant par > sont interprétées comme du code, tout le reste est considéré comme un commentaire. Une exigence supplémentaire est de toujours laisser une ligne vide avant et après le bloc de code : 

In Bird-style you have to leave a blank before the code.

> fact :: Integer -> Integer
> fact 0 = 1
> fact (n+1) = (n+1) * fact n

And you have to leave a blank line after the code as well.

La programmation littéraire peut également être effectuée en Haskell, en utilisant LaTeX . L'environnement de code peut être utilisé à la place du style de Richard Bird : Dans le style LaTeX , cela équivaut à l'exemple ci-dessus, l'environnement de code pourrait être défini dans le préambule LaTeX. Voici une définition simple : 

\usepackage{verbatim}
\newenvironment{code}{\verbatim}{\endverbatim}

plus tard dans 

% the LaTeX source file
The \verb|fact n| function call computes $n!$ if $n\ge 0$, here is a definition:\\
\begin{code}
fact :: Integer -> Integer
fact 0 = 1
fact (n+1) = (n+1) * fact n
\end{code}
Here more explanation using \LaTeX{} markup

Java

Ce fragment de code Java montre un commentaire de bloc utilisé pour décrire la setToolTipTextméthode. Le formatage est conforme aux normes Javadoc de Sun Microsystems . Le commentaire est conçu pour être lu par le processeur Javadoc. 

/**
 * This is a block comment in Java.
 * The setToolTipText method registers the text to display in a tool tip.
 * The text is displayed when the cursor lingers over the component.
 *
 * @param text  The string to be displayed.  If 'text' is null,
 *              the tool tip is turned off for this component.
 */
public void setToolTipText(String text) {
    // This is an inline comment in Java. TODO: Write code for this method.
}

JavaScript

JavaScript utilise // pour précéder les commentaires et /* */ pour les commentaires multilignes. 

// A single line JavaScript comment
var iNum = 100;
var iTwo = 2; // A comment at the end of line
/*
multi-line
JavaScript comment
*/

Lua

Le langage de programmation Lua utilise des tirets doubles, --, pour les commentaires sur une seule ligne de la même manière que les langages Ada , Eiffel , Haskell , SQL et VHDL . Lua a également des commentaires de bloc, qui commencent par --[[et s'exécutent jusqu'à une fermeture]]

Par exemple: 

--[[A multi-line
long comment
]]
print(20)   -- print the result

Une technique courante pour commenter un morceau de code consiste à placer le code entre --[[et --]], comme ci-dessous : 

--[[
print(10)
--]]
-- no action (commented out)

Dans ce cas, il est possible de réactiver le code en ajoutant un seul tiret à la première ligne : 

---[[
print(10)
--]]
--> 10

Dans le premier exemple, le --[[dans la première ligne commence un long commentaire et les deux tirets de la dernière ligne sont toujours à l'intérieur de ce commentaire. Dans le deuxième exemple, la séquence ---[[commence un commentaire ordinaire sur une seule ligne, de sorte que la première et la dernière ligne deviennent des commentaires indépendants. Dans ce cas, les printcommentaires sont extérieurs. Dans ce cas, la dernière ligne devient un commentaire indépendant, car elle commence par --.

Les commentaires longs en Lua peuvent être plus complexes que ceux-ci, comme vous pouvez le lire dans la section intitulée "Longues chaînes" cf Programmation en Lua .

MATLAB

Dans le langage de programmation de MATLAB , le caractère '%' indique un commentaire sur une seule ligne. Les commentaires multilignes sont également disponibles via les crochets %{ et %} et peuvent être imbriqués, par exemple 

% These are the derivatives for each term
d = [0 -1 0];

%{
  %{
    (Example of a nested comment, indentation is for cosmetics (and ignored).)
  %}
  We form the sequence, following the Taylor formula.
  Note that we're operating on a vector.
%}
seq = d .* (x - c).^n ./(factorial(n))

% We add-up to get the Taylor approximation
approx = sum(seq)

Nim

Nim utilise le caractère '#' pour les commentaires en ligne. Les commentaires de bloc multiligne sont ouverts avec '#[' et fermés avec ']#'. Les commentaires de blocs multilignes peuvent être imbriqués.

Nim a également des commentaires de documentation qui utilisent des balises mixtes Markdown et ReStructuredText . Les commentaires de documentation en ligne utilisent '##' et les commentaires de documentation de bloc multiligne sont ouverts avec '##[' et fermés avec ']##'. Le compilateur peut générer de la documentation HTML , LaTeX et JSON à partir des commentaires de la documentation. Les commentaires de documentation font partie de l' arbre de syntaxe abstraite et peuvent être extraits à l'aide de macros. 

## Documentation of the module *ReSTructuredText* and **MarkDown**
# This is a comment, but it is not a documentation comment.

type Kitten = object  ## Documentation of type
  age: int  ## Documentation of field

proc purr(self: Kitten) =
  ## Documentation of function
  echo "Purr Purr"  # This is a comment, but it is not a documentation comment.

# This is a comment, but it is not a documentation comment.

OCaml

OCaml utilise des commentaires imbriqués, ce qui est utile pour commenter un bloc de code. 

codeLine(* comment level 1(*comment level 2*)*)

Pascal

Dans la famille de langages pascal de Niklaus Wirth (y compris Modula-2 et Oberon ), les commentaires sont ouverts avec '(*' et complétés avec '*)'.

par exemple: 

(* test diagonals *)
columnDifference := testColumn - column;
if (row + columnDifference = testRow) or
    .......

Dans les dialectes modernes de Pascal, '{' et '}' sont utilisés à la place.

Perl

Les commentaires de ligne en Perl et dans de nombreux autres langages de script commencent par un symbole dièse (#). 

# A simple example
# 
my $s = "Wikipedia"; # Sets the variable s to "Wikipedia".
print $s . "\n";     # Add a newline character after printing

Au lieu d'une construction de commentaire de bloc régulière, Perl utilise Plain Old Documentation , un langage de balisage pour la programmation littéraire , par exemple : 

=item Pod::List-E<gt>new()

Create a new list object. Properties may be specified through a hash
reference like this:

  my $list = Pod::List->new({ -start => $., -indent => 4 });

See the individual methods/properties for details.

=cut

sub new {
    my $this = shift;
    my $class = ref($this) || $this;
    my %params = @_;
    my $self = {%params};
    bless $self, $class;
    $self->initialize();
    return $self;
}

R

R ne prend en charge que les commentaires en ligne commencés par le caractère dièse (#). 

# This is a comment
print("This is not a comment")  # This is another comment

Raku

Raku (précédemment appelé Perl 6) utilise les mêmes commentaires de ligne et les mêmes commentaires de documentation POD que Perl standard (voir la section Perl ci-dessus), mais ajoute un type de commentaire de bloc configurable : « commentaires multilignes / intégrés ».

Ceux-ci commencent par un caractère dièse, suivi d'un backtick, puis d'un caractère de crochet d'ouverture, et se terminent par le caractère de crochet de fermeture correspondant. Le contenu peut non seulement s'étendre sur plusieurs lignes, mais peut également être intégré en ligne. 

#`{{ "commenting out" this version 
toggle-case(Str:D $s)

Toggles the case of each character in a string:

  my Str $toggled-string = toggle-case("mY NAME IS mICHAEL!");

}}

sub toggle-case(Str:D $s) #`( this version of parens is used now ){
    ...
}

PHP

Les commentaires en PHP peuvent être soit dans le style C++ (à la fois en ligne et en bloc), soit utiliser des hachages. PHPDoc est un style adapté de Javadoc et est un standard commun pour documenter le code PHP.

PowerShell

Commentaires dans Windows PowerShell 

# Single line comment
Write-Host "Hello, World!"

<# Multi
   Line
   Comment #>

Write-Host "Goodbye, world!"

Python

Les commentaires en ligne en Python utilisent le caractère dièse (#), comme dans les deux exemples de ce code : 

# This program prints "Hello World" to the screen
print("Hello World!")  # Note the new syntax

Les commentaires de blocage, tels que définis dans cet article, n'existent techniquement pas en Python. Un littéral de chaîne nue représenté par une chaîne entre guillemets triples peut être utilisé, mais n'est pas ignoré par l'interpréteur de la même manière que le commentaire "#". Dans les exemples ci-dessous, les chaînes triples entre guillemets agissent ainsi comme des commentaires, mais sont également traitées comme des docstrings : 

"""
Assuming this is file mymodule.py, then this string, being the
first statement in the file, will become the "mymodule" module's
docstring when the file is imported.
"""

class MyClass:
    """The class's docstring"""

    def my_method(self):
        """The method's docstring"""

def my_function():
    """The function's docstring"""

Rubis

Commentaires en Ruby .

Commentaire sur une seule ligne : (la ligne commence par un dièse "#") 

puts "This is not a comment"

# this is a comment

puts "This is not a comment"

Commentaires sur plusieurs lignes : (les commentaires se placent entre les mots-clés « debut » et « fin ») 

puts "This is not a comment"

=begin

whatever goes in these lines

is just for the human reader

=end

puts "This is not a comment"

SQL

Les commentaires standard en SQL sont sous forme d'une seule ligne, en utilisant deux tirets : 

-- This is a single line comment
-- followed by a second line
SELECT COUNT(*)
       FROM Authors
       WHERE Authors.name = 'Smith'; -- Note: we only want 'smith'
                                     -- this comment appears after SQL code

Alternativement, une syntaxe de format de commentaire identique au style "block comment" utilisé dans la syntaxe pour C et Java est prise en charge par Transact-SQL , MySQL , SQLite , PostgreSQL et Oracle .

MySQL prend également en charge les commentaires du caractère dièse (#) à la fin de la ligne.

Rapide

Les commentaires sur une seule ligne commencent par deux barres obliques (//) :

// This is a comment.

Les commentaires multilignes commencent par une barre oblique suivie d'un astérisque (/*) et se terminent par un astérisque suivi d'une barre oblique (*/) :

/* This is also a comment
 but is written over multiple lines. */

Les commentaires multilignes dans Swift peuvent être imbriqués dans d'autres commentaires multilignes. Vous écrivez des commentaires imbriqués en commençant un bloc de commentaires multiligne, puis en commençant un deuxième commentaire multiligne dans le premier bloc. Le deuxième bloc est alors fermé, suivi du premier bloc :

/* This is the start of the first multiline comment.
 /* This is the second, nested multiline comment. */
 This is the end of the first multiline comment. */

XML (ou HTML)

Les commentaires en XML (ou HTML) sont introduits avec

<!--

et peut s'étaler sur plusieurs lignes jusqu'au terminateur, 

-->

Par exemple, 

<!-- select the context here -->
<param name="context" value="public" />

Pour des raisons de compatibilité avec SGML , la chaîne "--" (double tiret) n'est pas autorisée dans les commentaires.

Les problèmes de sécurité

Dans les langues interprétées, les commentaires sont visibles par l'utilisateur final du programme. Dans certains cas, tels que des sections de code qui sont "commentées", cela peut présenter une faille de sécurité .

Voir également

Notes et références

Lectures complémentaires

Liens externes