Worldlex Wiki En programmation , un commentaire est un texte intégré au code source qu'un traducteur ( compilateur ou interpréteur ) ignore. Généralement, un commentaire est une annotation destinée à faciliter la compréhension du code par le programmeur langage de programmation , un langage de balisage , un fichier de configuration et tout contexte similaire. Certains outils de développement , autres qu'un traducteur de code source, analysent les commentaires pour offrir des fonctionnalités telles que la génération de documentation API , l'analyse statique et l'intégration du contrôle de version . La syntaxe des commentaires varie selon les langages de programmation, mais on observe des schémas syntaxiques récurrents et des similitudes quant au contenu des commentaires.
La flexibilité permise par les commentaires autorise une grande variabilité dans le style du contenu. Afin de promouvoir l'uniformité, les conventions de style font généralement partie d'un guide de style de programmation . Cependant, les bonnes pratiques sont controversées et parfois contradictoires.
délimité par un texte qui marque le début et la fin du commentaire. Il peut s'étendre sur plusieurs lignes ou occuper n'importe quelle partie d'une ligne. Certains langages autorisent l'imbrication récursive des commentaires de bloc, tandis que d'autres ne le permettent pas. Un commentaire de ligne se termine à la fin de la ligne de texte. Dans les langages modernes, un commentaire de ligne commence par un délimiteur, mais certains langages plus anciens désignent une colonne à partir de laquelle le texte suivant est considéré comme un commentaire. De nombreux langages prennent en charge à la fois les commentaires de bloc et les commentaires de ligne C , C++ et leurs nombreux dérivés prennent en charge les commentaires de bloc délimités par `\`/*et `\` */et les commentaires de ligne délimités par `\` //. D'autres langages ne prennent en charge qu'un seul type de commentaire. Les commentaires peuvent également être classés en deux catégories : les commentaires prologues et les commentaires en ligne, selon leur position et leur contenu par rapport au code du programme. Un commentaire prologue est un commentaire (ou un groupe de commentaires associés) situé en haut d’une section du programme, par exemple avant une déclaration de symbole ou en haut d’un fichier. Un commentaire en ligne est un commentaire situé sur la même ligne et à droite du code auquel il se rapporte. Les commentaires prologues et les commentaires en ligne peuvent être représentés sous forme de commentaires de ligne ou de commentaires de bloc. Par exemple :
The example below explains why an insertion sort was chosen instead of a quicksort, as the former is, in theory, slower than the latter.
/* loop backwards through all elements returned by the server (they should be processed chronologically)*/for(i=(numElementsReturned-0);i>=1;i--){/* process each element's data */updatePattern(i,returnedElements[i]);}
Sometimes code contains a novel or noteworthy solution that warrants an explanatory comment. Such explanations might be lengthy and include diagrams and formal mathematical proofs. This may describe what the code does rather than intent, but may be useful for maintaining the code. This might apply for highly specialized problem domains or rarely used optimizations, constructs or function-calls.
When some aspect of the code is based on information in an external reference, comments link to the reference. For example as a URL or book name and page number.
Comment out
Une pratique courante chez les développeurs consiste à commenter une ou plusieurs lignes de code. Le programmeur ajoute une syntaxe de commentaire qui transforme le code du programme en commentaires, de sorte que le code exécutable ne soit plus exécuté à l'exécution. Cette technique est parfois utilisée pour trouver la cause d'un bogue. En commentant et en exécutant systématiquement des parties du programme, il est possible de localiser le code source incriminé.
De nombreux IDE permettent d'ajouter et de supprimer des commentaires grâce à des actions d'interface utilisateur pratiques , telles qu'un raccourci clavier .des métadonnées sur le code. Ces métadonnées incluent généralement le nom de l'auteur original et des mainteneurs successifs, les dates de première rédaction et de modification, un lien vers la documentation de développement et la documentation utilisateur, ainsi que des informations légales telles que les droits d'auteur et la licence du logiciel . Plus rarement, des données binaires encodées en texte peuvent y être incluses.
Certains outils de programmation intègrent des métadonnées au code sous forme de commentaires. Par exemple, un outil de gestion de versions peut inscrire des métadonnées telles que l'auteur, la date et le numéro de version dans chaque fichier lors de son intégration au dépôt.
Intégrer aux outils de développement
Il arrive que des informations contenues dans les commentaires soient utilisées par des outils de développement autres que le traducteur éditeurs de code source permettent la configuration via les métadonnées des commentaires. Un exemple particulier est la fonctionnalité de ligne de mode de Vim , qui permet de configurer la gestion du caractère de tabulation. Par exemple :
# vim: tabstop=8 expandtab shiftwidth=4 softtabstop=4
Génération de documentation d'assistancegénérateur de documentation API analyse les informations d'une base de code pour générer la documentation API. Nombre d'entre eux permettent de lire les informations des commentaires, souvent en analysant les métadonnées, afin de contrôler le contenu et la mise en forme du document résultant.Bien que certains affirment que la documentation API est de meilleure qualité lorsqu'elle est rédigée de manière plus traditionnelle et manuelle, d'autres soutiennent que le stockage des informations de documentation dans les commentaires du code simplifie le processus de documentation et augmente la probabilité que celle-ci soit maintenue à jour. Parmi les exemples, citons Javadoc , Ddoc, Doxygen , Visual Expert et PHPDoc . Les docstrings 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 », lus par IntelliSense à partir de l'assembly .NET compilé .
Visualisation
Une visualisation en art ASCII telle qu'un logo , un diagramme ou un organigramme peut être incluse dans un commentaire.
L'extrait de code suivant illustre le flux de processus d'un script d'administration système ( fichier de script Windows ). Bien qu'une section marquant le code apparaisse comme un commentaire, le diagramme se trouve dans une section CDATA XML , qui, techniquement, n'est pas un commentaire, mais remplit la même fonction ici. Bien que ce diagramme puisse figurer dans un commentaire, cet exemple illustre un cas où le programmeur a choisi de ne pas utiliser de commentaire pour inclure des ressources dans le code source.
> <![CDATA[ HostApp (Main_process) | V script.wsf (app_cmd) --> ClientApp (async_run, batch_process) | | V mru.ini (mru_history) ]]> </resource>processus de développement de documents
Parfois, les commentaires décrivent les processus de développement liés au code. Par exemple, ils peuvent décrire comment compiler le code ou comment soumettre des modifications au responsable de la maintenance du logiciel .
Étendre la syntaxe du langage
Il arrive que du code formaté comme un commentaire soit surchargé afin de transmettre des informations supplémentaires au traducteur, comme des commentaires conditionnels. Ainsi, une syntaxe généralement associée à un commentaire peut en réalité représenter du code du programme, et non du code de commentaire. Cette syntaxe peut constituer un moyen pratique de maintenir la compatibilité tout en ajoutant des fonctionnalités, mais certains la considèrent comme une solution de fortune .
D'autres exemples incluent les directives de l'interpréteur :
- Le « shebang » Unix
#!– utilisé sur la première ligne d'un script pour indiquer l'interpréteur à utiliser. - « Commentaires magiques » identifiant l’encodage utilisé par un fichier source, par exemple la PEP 263 de Python.
Le script ci-dessous, destiné à un système de type Unix, illustre ces deux utilisations :
)Le compilateur gcc (depuis 2017) recherche un commentaire dans une instruction switch si un cas entraîne le passage au cas suivant. Si aucune indication explicite de passage n'est trouvée, le compilateur émet un avertissement concernant un problème de codage potentiel. L'insertion d'un tel commentaire est une convention établie de longue date, et le compilateur a formalisé cette pratique. Par exemple :
un langage grossier . Points de vue normatifs
Il existe diverses conceptions normatives et des opinions bien établies concernant l’utilisation appropriée des commentaires dans le code source. Certaines sont informelles et basées sur des préférences personnelles, tandis que d’autres sont publiées ou diffusées sous forme de directives officielles pour une communauté particulière.
Besoin de commentaires
Les experts ont des avis divergents quant à la pertinence et au moment opportun des commentaires dans le code source. Certains affirment que le code source doit être écrit avec peu de commentaires, partant du principe qu'il doit être explicite et auto-documenté . D'autres suggèrent qu'il doit être abondamment commenté (il n'est pas rare que plus de 50 % des caractères non blancs du code source soient contenus dans des commentaires).
Entre ces deux points de vue se trouve l'affirmation selon laquelle les commentaires ne sont ni bénéfiques ni nuisibles en soi, et que l'important est qu'ils soient corrects et mis à jour en fonction du code source, et qu'ils soient supprimés 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 en programmation.
Niveau de détail
En fonction du public cible du 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 à un ouvrage d'introduction destiné à l'enseignement de la programmation aux débutants :
; /* Attribue la valeur "Wikipedia" à la variable s. */Ce niveau de détail ne serait toutefois pas approprié dans le contexte du code de production, ni dans d'autres situations impliquant des développeurs expérimentés. De telles descriptions rudimentaires sont incompatibles avec la recommandation : « De bons commentaires… clarifient l'intention. » De plus, dans les environnements de développement professionnels, le niveau de détail est généralement bien défini afin de répondre à une exigence de performance spécifique imposée par les opérations métier.
Styles
Les commentaires, en tant que texte libre, peuvent être mis en forme de multiples façons. Nombreux sont ceux qui privilégient un style cohérent, non intrusif, facile à modifier et difficile à enfreindre. Certains estimant qu'un certain niveau de cohérence est précieux et pertinent, un style de commentaires uniforme est parfois convenu avant le début d'un projet ou se dégage au fur et à mesure de son développement.
Les extraits de code C suivants illustrent la diversité des styles de commentaires de bloc :
éditeur de code source ne formatant pas automatiquement les commentaires comme dans le second exemple.Allen Holub, consultant en logiciels et commentateur technologique , préconise d'aligner les bords gauches des commentaires :
étiquette , un code ou un jeton. Certains éditeurs mettent en évidence un commentaire en fonction de son étiquette.Les balises couramment utilisées incluent :
- BUG, DEBUG — signale un bogue connu , ce qui peut indiquer qu'il devrait être corrigé.
- FIXME — indique qu'il y a du travail à faire pour corriger un bug
- BRICOLAGE, BRAQUAGE, SOLUTION DE MALADIE — désigne une solution qui pourrait être considérée comme de mauvaise qualité.
- À FAIRE — décrit du travail à faire
- NOTE — informations relativement générales
- ANNULÉ — une annulation ou un « retour en arrière » du code précédent
Par exemple:
langages à accolades, tels que C, C++ et leurs nombreux dérivés, délimitent un commentaire de ligne par `\` la version C99 . Parmi les langages notables, citons : C, C++, C# , D , Java , JavaScript et Swift . Par exemple :langages de script, il est courant de délimiter un commentaire de ligne par un point #. La prise en charge des commentaires de bloc varie. Parmi les langages notables, citons : Bash , Raku , Ruby , Perl , PowerShell , Python et R.Un exemple en R :
) # Ceci est un autre commentaireBloc en Ruby
Un commentaire de bloc est délimité par =begindes caractères spéciaux =endqui marquent le début d'une ligne. Par exemple :
# ceci est un commentaire puts "pas un commentaire" =début Ce qui se trouve dans ces lignes est destiné uniquement au lecteur humain =fin puts "pas un commentaire"Bloc en Perl
Au lieu d'une structure de commentaires de bloc régulière, Perl utilise le balisage de documentation simple et classique de la programmation littéraire (POD) . Par exemple :
Perl , mais ajoute un type de commentaire de bloc configurable : « commentaires multilignes / imbriqués ». Il commence par #`un caractère suivi d’une accolade ouvrante et se termine par l’accolade fermante correspondante. Par exemple :de toggle-case(Str:D $s) Inverse la casse de chaque caractère d'une chaîne : my Str $toggled-string = toggle-case("mon NOM EST mICHAEL!"); }} sub toggle-case ( Str:D $s ) #`( cette version de parenthèses est maintenant utilisée ) { ... } Blocage dans PowerShell
PowerShell prend en charge les commentaires de bloc délimités par `<br>` <#et `<p> #>`. Par exemple :
une chaîne de caractères littérale nue , représentée par une chaîne entre triples guillemets, est souvent utilisée à cette fin. Dans les exemples ci-dessous, les chaînes entre triples guillemets doubles se comportent comme des commentaires, mais sont également traitées comme des docstrings :def my_method ( self ): Documentation de la méthode"""Balisage du navigateur
Les langages de balisage varient généralement dans leur syntaxe des commentaires, mais certains formats de balisage Internet importants, tels que HTML et XML, délimitent un commentaire de bloc avec `<b>` <!--et `</b>` et ne prennent pas en charge les commentaires de ligne. Exemple en XML :-->
value= "public" />Pour assurer la compatibilité avec SGML , le double tiret (--) n'est pas autorisé à l'intérieur des commentaires.
ColdFusion offre une syntaxe similaire à celle des commentaires HTML , mais utilise trois tirets au lieu de deux. CodeFusion permet l'imbrication de commentaires de bloc.
Bloc en Haskell
En Haskell, un commentaire de bloc est délimité par `\ {-n` et `\p` -}. Par exemple :
-- ceci est un autre commentaireHaskell propose également une méthode de programmation littéraire pour commenter le code, appelée « style Bird » . Les lignes commençant par >`<script>` sont interprétées comme du code, et tout le reste comme un commentaire. Une condition supplémentaire est la présence d'une ligne vide avant et après le bloc de 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. " En style Bird, il faut laisser un espace avant le code. > fait :: Entier -> Entier > fait 0 = 1 > fait ( n + 1 ) = ( n + 1 ) * fait n Et vous devez également laisser une ligne vide après le code.
La programmation littéraire peut également être réalisée via LaTeX . Exemple de définition :
Transact-SQL , MySQL , SQLite , PostgreSQL et Oracle . MySQL prend également en charge les commentaires de ligne délimités par des points #.
Syntaxe moins courante
APL
APL utilise ⍝(« lampe ») pour un commentaire de ligne. Par exemple :
AppleScript prend en charge les commentaires de ligne et les commentaires de bloc. Par exemple :end greet-- Afficher le message de salutation greet ( "Bonjour" )BASIQUEBASIC utilisaient 30 GOTO 20
Dans les versions ultérieures, notamment Quick Basic , Q Basic , Visual Basic (VB), VB.NET , VBScript , FreeBASIC et Gambas , un commentaire de ligne est délimité par 'une apostrophe. Exemple en VB.NET :
) ' afficher une boîte de dialogue avec un message de bienvenue End Sub End ClassConfiguration de 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 ; cependant, ces commentaires ne sont ni 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 partie intégrante de la configuration et qui peut être enregistré dans la configuration de démarrage NVRAM via :
- La commande « description » permet d'ajouter une description à la configuration d'une interface ou d'un voisin BGP.
- Le paramètre « name » permet d'ajouter une remarque à un itinéraire statique.
- La commande « remark » dans les listes d'accès
L'extrait de code Fortran suivant, en format fixe, montre que la syntaxe des commentaires est orientée colonnes. Une lettre Cen première colonne indique que la ligne entière est considérée comme un commentaire. En Fortran 77 , un astérisque en première colonne indique également un commentaire.L'extrait de code Fortran 90 suivant illustre une syntaxe de commentaire de ligne plus moderne : texte suivant !.de préprocesseur optionnelle de type C. Celle-ci peut servir à ajouter des commentaires de bloc :MATLAB , le caractère « % » indique un commentaire sur une seule ligne. Les commentaires multilignes sont également disponibles via les accolades %{ et %} et peuvent être imbriqués, par exemple :Nim délimite les commentaires de ligne avec `\` #et les commentaires de bloc avec `\` #[et `\ ]#`. Les commentaires de bloc peuvent être imbriqués.Nim propose également des commentaires de documentation utilisant un mélange de balises Markdown et ReStructuredText . Un commentaire de documentation sur une ligne utilise « ## », tandis qu’un commentaire de documentation sur un bloc utilise « ##[ » et « ]## ». Le compilateur peut générer de la documentation HTML , LaTeX et JSON à partir de ces commentaires. Ces derniers font partie de l’ arbre de syntaxe abstraite et peuvent être extraits à l’aide de macros.
# Ceci est un commentaire, mais ce n'est pas un commentaire de documentation.# Ceci est un commentaire, mais ce n'est pas un commentaire de documentation.OCaml
OCaml prend en charge les commentaires imbriqués. Par exemple :
Pascal et Delphi , un commentaire de bloc est délimité par ` {\` et ` }\`, et, pour les ordinateurs ne prenant pas en charge ces caractères, `\` (*est *)également accepté. Un commentaire de ligne est délimité par ` \` \\. Dans la famille de langages plus modernes de Niklaus Wirth (dont Modula-2 et Oberon ), les commentaires sont délimités par `\` (*et `\` *). Les commentaires peuvent être imbriqués. Par exemple :PHP, les commentaires peuvent être encadrés par des accolades (sur une ligne ou dans un bloc) ou séparés par la lettre #`l`. Les blocs ne peuvent pas être imbriqués. Depuis PHP 8, un #commentaire n'est considéré comme tel que s'il n'est pas immédiatement suivi d'un autre commentaire [. Sinon, il délimite un attribut, qui se poursuit jusqu'au prochain commentaire ]. Par exemple :value = $value; } } " /** * Cette classe contient un exemple de documentation. * @author Inconnu */ #[ Attribute ] class MyAttribute { const VALUE = 'value' ; // Commentaire de ligne style C++ private $value ; # Commentaire de ligne style script public function __construct ( $value = null ) { $this -> value = $value ; } }
Double tiret
Un ensemble relativement hétérogène de langages utilise --les commentaires sur une seule ligne. Parmi les langages notables, citons : Ada , Eiffel , Haskell , Lua , SQL et VHDL . La prise en charge des commentaires de bloc varie. Exemple en Ada :
les langages interprétés , selon les capacités du système d'exploitation et les choix de l'administrateur, l'intégralité du code source, y compris les commentaires, peut être visible par l' utilisateur final du programme . Cela peut présenter une faille de sécurité lorsque les commentaires contiennent des informations confidentielles ou lorsque des sections de code confidentielles sont simplement commentées.
Visualisation
Une visualisation en art ASCII telle qu'un logo , un diagramme ou un organigramme peut être incluse dans un commentaire.
L'extrait de code suivant illustre le flux de processus d'un script d'administration système ( fichier de script Windows ). Bien qu'une section marquant le code apparaisse comme un commentaire, le diagramme se trouve dans une section CDATA XML , qui, techniquement, n'est pas un commentaire, mais remplit la même fonction ici. Bien que ce diagramme puisse figurer dans un commentaire, cet exemple illustre un cas où le programmeur a choisi de ne pas utiliser de commentaire pour inclure des ressources dans le code source.
processus de développement de documents
Parfois, les commentaires décrivent les processus de développement liés au code. Par exemple, ils peuvent décrire comment compiler le code ou comment soumettre des modifications au responsable de la maintenance du logiciel .
Étendre la syntaxe du langage
Il arrive que du code formaté comme un commentaire soit surchargé afin de transmettre des informations supplémentaires au traducteur, comme des commentaires conditionnels. Ainsi, une syntaxe généralement associée à un commentaire peut en réalité représenter du code du programme, et non du code de commentaire. Cette syntaxe peut constituer un moyen pratique de maintenir la compatibilité tout en ajoutant des fonctionnalités, mais certains la considèrent comme une solution de fortune .
D'autres exemples incluent les directives de l'interpréteur :
- Le « shebang » Unix
#!– utilisé sur la première ligne d'un script pour indiquer l'interpréteur à utiliser. - « Commentaires magiques » identifiant l’encodage utilisé par un fichier source, par exemple la PEP 263 de Python.
Le script ci-dessous, destiné à un système de type Unix, illustre ces deux utilisations :
Le compilateur gcc (depuis 2017) recherche un commentaire dans une instruction switch si un cas entraîne le passage au cas suivant. Si aucune indication explicite de passage n'est trouvée, le compilateur émet un avertissement concernant un problème de codage potentiel. L'insertion d'un tel commentaire est une convention établie de longue date, et le compilateur a formalisé cette pratique. Par exemple :
Points de vue normatifs
Il existe diverses conceptions normatives et des opinions bien établies concernant l’utilisation appropriée des commentaires dans le code source. Certaines sont informelles et basées sur des préférences personnelles, tandis que d’autres sont publiées ou diffusées sous forme de directives officielles pour une communauté particulière.
Besoin de commentaires
Les experts ont des avis divergents quant à la pertinence et au moment opportun des commentaires dans le code source. Certains affirment que le code source doit être écrit avec peu de commentaires, partant du principe qu'il doit être explicite et auto-documenté . D'autres suggèrent qu'il doit être abondamment commenté (il n'est pas rare que plus de 50 % des caractères non blancs du code source soient contenus dans des commentaires).
Entre ces deux points de vue se trouve l'affirmation selon laquelle les commentaires ne sont ni bénéfiques ni nuisibles en soi, et que l'important est qu'ils soient corrects et mis à jour en fonction du code source, et qu'ils soient supprimés 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 en programmation.
Niveau de détail
En fonction du public cible du 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 à un ouvrage d'introduction destiné à l'enseignement de la programmation aux débutants :
Ce niveau de détail ne serait toutefois pas approprié dans le contexte du code de production, ni dans d'autres situations impliquant des développeurs expérimentés. De telles descriptions rudimentaires sont incompatibles avec la recommandation : « De bons commentaires… clarifient l'intention. » De plus, dans les environnements de développement professionnels, le niveau de détail est généralement bien défini afin de répondre à une exigence de performance spécifique imposée par les opérations métier.
Styles
Les commentaires, en tant que texte libre, peuvent être mis en forme de multiples façons. Nombreux sont ceux qui privilégient un style cohérent, non intrusif, facile à modifier et difficile à enfreindre. Certains estimant qu'un certain niveau de cohérence est précieux et pertinent, un style de commentaires uniforme est parfois convenu avant le début d'un projet ou se dégage au fur et à mesure de son développement.
Les extraits de code C suivants illustrent la diversité des styles de commentaires de bloc :
Allen Holub, consultant en logiciels et commentateur technologique , préconise d'aligner les bords gauches des commentaires :
Les balises couramment utilisées incluent :
- BUG, DEBUG — signale un bogue connu , ce qui peut indiquer qu'il devrait être corrigé.
- FIXME — indique qu'il y a du travail à faire pour corriger un bug
- BRICOLAGE, BRAQUAGE, SOLUTION DE MALADIE — désigne une solution qui pourrait être considérée comme de mauvaise qualité.
- À FAIRE — décrit du travail à faire
- NOTE — informations relativement générales
- ANNULÉ — une annulation ou un « retour en arrière » du code précédent
Par exemple:
la version C99 . Parmi les langages notables, citons : C, C++, C# , D , Java , JavaScript et Swift . Par exemple :langages de script, il est courant de délimiter un commentaire de ligne par un point #. La prise en charge des commentaires de bloc varie. Parmi les langages notables, citons : Bash , Raku , Ruby , Perl , PowerShell , Python et R.Un exemple en R :
) # Ceci est un autre commentaireBloc en Ruby
Un commentaire de bloc est délimité par =begindes caractères spéciaux =endqui marquent le début d'une ligne. Par exemple :
# ceci est un commentaire puts "pas un commentaire" =début Ce qui se trouve dans ces lignes est destiné uniquement au lecteur humain =fin puts "pas un commentaire"Bloc en Perl
Au lieu d'une structure de commentaires de bloc régulière, Perl utilise le balisage de documentation simple et classique de la programmation littéraire (POD) . Par exemple :
Perl , mais ajoute un type de commentaire de bloc configurable : « commentaires multilignes / imbriqués ». Il commence par #`un caractère suivi d’une accolade ouvrante et se termine par l’accolade fermante correspondante. Par exemple :de toggle-case(Str:D $s) Inverse la casse de chaque caractère d'une chaîne : my Str $toggled-string = toggle-case("mon NOM EST mICHAEL!"); }} sub toggle-case ( Str:D $s ) #`( cette version de parenthèses est maintenant utilisée ) { ... } Blocage dans PowerShell
PowerShell prend en charge les commentaires de bloc délimités par `<br>` <#et `<p> #>`. Par exemple :
une chaîne de caractères littérale nue , représentée par une chaîne entre triples guillemets, est souvent utilisée à cette fin. Dans les exemples ci-dessous, les chaînes entre triples guillemets doubles se comportent comme des commentaires, mais sont également traitées comme des docstrings :def my_method ( self ): Documentation de la méthode"""Balisage du navigateur
Les langages de balisage varient généralement dans leur syntaxe des commentaires, mais certains formats de balisage Internet importants, tels que HTML et XML, délimitent un commentaire de bloc avec `<b>` <!--et `</b>` et ne prennent pas en charge les commentaires de ligne. Exemple en XML :-->
value= "public" />Pour assurer la compatibilité avec SGML , le double tiret (--) n'est pas autorisé à l'intérieur des commentaires.
ColdFusion offre une syntaxe similaire à celle des commentaires HTML , mais utilise trois tirets au lieu de deux. CodeFusion permet l'imbrication de commentaires de bloc.
Bloc en Haskell
En Haskell, un commentaire de bloc est délimité par `\ {-n` et `\p` -}. Par exemple :
-- ceci est un autre commentaireHaskell propose également une méthode de programmation littéraire pour commenter le code, appelée « style Bird » . Les lignes commençant par >`<script>` sont interprétées comme du code, et tout le reste comme un commentaire. Une condition supplémentaire est la présence d'une ligne vide avant et après le bloc de 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. " En style Bird, il faut laisser un espace avant le code. > fait :: Entier -> Entier > fait 0 = 1 > fait ( n + 1 ) = ( n + 1 ) * fait n Et vous devez également laisser une ligne vide après le code.
La programmation littéraire peut également être réalisée via LaTeX . Exemple de définition :
Transact-SQL , MySQL , SQLite , PostgreSQL et Oracle . MySQL prend également en charge les commentaires de ligne délimités par des points #.
Syntaxe moins courante
APL
APL utilise ⍝(« lampe ») pour un commentaire de ligne. Par exemple :
AppleScript prend en charge les commentaires de ligne et les commentaires de bloc. Par exemple :end greet-- Afficher le message de salutation greet ( "Bonjour" )BASIQUEBASIC utilisaient 30 GOTO 20
Dans les versions ultérieures, notamment Quick Basic , Q Basic , Visual Basic (VB), VB.NET , VBScript , FreeBASIC et Gambas , un commentaire de ligne est délimité par 'une apostrophe. Exemple en VB.NET :
) ' afficher une boîte de dialogue avec un message de bienvenue End Sub End ClassConfiguration de 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 ; cependant, ces commentaires ne sont ni 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 partie intégrante de la configuration et qui peut être enregistré dans la configuration de démarrage NVRAM via :
- La commande « description » permet d'ajouter une description à la configuration d'une interface ou d'un voisin BGP.
- Le paramètre « name » permet d'ajouter une remarque à un itinéraire statique.
- La commande « remark » dans les listes d'accès
L'extrait de code Fortran suivant, en format fixe, montre que la syntaxe des commentaires est orientée colonnes. Une lettre Cen première colonne indique que la ligne entière est considérée comme un commentaire. En Fortran 77 , un astérisque en première colonne indique également un commentaire.L'extrait de code Fortran 90 suivant illustre une syntaxe de commentaire de ligne plus moderne : texte suivant !.de préprocesseur optionnelle de type C. Celle-ci peut servir à ajouter des commentaires de bloc :MATLAB , le caractère « % » indique un commentaire sur une seule ligne. Les commentaires multilignes sont également disponibles via les accolades %{ et %} et peuvent être imbriqués, par exemple :Nim délimite les commentaires de ligne avec `\` #et les commentaires de bloc avec `\` #[et `\ ]#`. Les commentaires de bloc peuvent être imbriqués.Nim propose également des commentaires de documentation utilisant un mélange de balises Markdown et ReStructuredText . Un commentaire de documentation sur une ligne utilise « ## », tandis qu’un commentaire de documentation sur un bloc utilise « ##[ » et « ]## ». Le compilateur peut générer de la documentation HTML , LaTeX et JSON à partir de ces commentaires. Ces derniers font partie de l’ arbre de syntaxe abstraite et peuvent être extraits à l’aide de macros.
# Ceci est un commentaire, mais ce n'est pas un commentaire de documentation.# Ceci est un commentaire, mais ce n'est pas un commentaire de documentation.OCaml
OCaml prend en charge les commentaires imbriqués. Par exemple :
Pascal et Delphi , un commentaire de bloc est délimité par ` {\` et ` }\`, et, pour les ordinateurs ne prenant pas en charge ces caractères, `\` (*est *)également accepté. Un commentaire de ligne est délimité par ` \` \\. Dans la famille de langages plus modernes de Niklaus Wirth (dont Modula-2 et Oberon ), les commentaires sont délimités par `\` (*et `\` *). Les commentaires peuvent être imbriqués. Par exemple :PHP, les commentaires peuvent être encadrés par des accolades (sur une ligne ou dans un bloc) ou séparés par la lettre #`l`. Les blocs ne peuvent pas être imbriqués. Depuis PHP 8, un #commentaire n'est considéré comme tel que s'il n'est pas immédiatement suivi d'un autre commentaire [. Sinon, il délimite un attribut, qui se poursuit jusqu'au prochain commentaire ]. Par exemple :value = $value; } } " /** * Cette classe contient un exemple de documentation. * @author Inconnu */ #[ Attribute ] class MyAttribute { const VALUE = 'value' ; // Commentaire de ligne style C++ private $value ; # Commentaire de ligne style script public function __construct ( $value = null ) { $this -> value = $value ; } }
Double tiret
Un ensemble relativement hétérogène de langages utilise --les commentaires sur une seule ligne. Parmi les langages notables, citons : Ada , Eiffel , Haskell , Lua , SQL et VHDL . La prise en charge des commentaires de bloc varie. Exemple en Ada :
les langages interprétés , selon les capacités du système d'exploitation et les choix de l'administrateur, l'intégralité du code source, y compris les commentaires, peut être visible par l' utilisateur final du programme . Cela peut présenter une faille de sécurité lorsque les commentaires contiennent des informations confidentielles ou lorsque des sections de code confidentielles sont simplement commentées.