Quel style de commentaire dois-je utiliser dans les fichiers batch?

J'ai écrit quelques fichiers batch et j'ai rencontré ce guide de l'utilisateur , qui a été assez informatif. Cela m'a montré que les lignes peuvent être commentées non seulement avec REM, mais aussi avec ::. Ça dit:

Les commentaires dans le code de lot peuvent être faits à l'aide de deux points, c'est mieux que d'utiliser la commande REM car les étiquettes sont traitées avant les symboles de redirection. ::<remark>ne pose aucun problème mais rem <remark>produit des erreurs.

Pourquoi alors, la plupart des guides et exemples que je vois utilisent-ils la REMcommande? Fonctionne-t-il ::sur toutes les versions de Windows?

tl; dr: REM est la manière documentée et prise en charge d'incorporer des commentaires dans des fichiers batch.

::est essentiellement une étiquette vierge qui ne peut jamais être sautée, alors que REMc'est une commande réelle qui ne fait rien. Dans aucun des cas (du moins sous Windows 7), la présence d'opérateurs de redirection ne pose problème.

Cependant, il ::est connu qu'il se comporte mal dans des blocs dans certaines circonstances, étant analysé non pas comme une étiquette mais comme une sorte de lettre de lecteur. Je suis un peu flou sur l'endroit exact, mais cela suffit à lui seul pour me faire utiliser REMexclusivement. C'est le moyen documenté et pris en charge d'incorporer des commentaires dans des fichiers de commandes, alors qu'il ::s'agit simplement d'un artefact d'une implémentation particulière.

Voici un exemple où ::produit un problème dans une FORboucle.

Cet exemple ne fonctionnera pas dans un fichier appelé test.batsur votre bureau:

@echo off
for /F "delims=" %%A in ('type C:\Users\%username%\Desktop\test.bat') do (
    ::echo hello>C:\Users\%username%\Desktop\text.txt
)
pause

Bien que cet exemple fonctionne correctement en tant que commentaire:

@echo off
for /F "delims=" %%A in ('type C:\Users\%username%\Desktop\test.bat') do (
    REM echo hello>C:\Users\%username%\Desktop\text.txt
)
pause

Le problème semble provenir de la redirection de la sortie vers un fichier. Ma meilleure supposition est qu'il interprète ::comme une étiquette d'échappement appelée :echo.

Commentaires avec REM

A REMpeut remarquer une ligne complète, également un caret multiligne à la fin de la ligne, si ce n'est pas la fin du premier jeton.

REM This is a comment, the caret is ignored^
echo This line is printed

REM This_is_a_comment_the_caret_appends_the_next_line^
echo This line is part of the remark

REM suivi de certains caractères .:\/=fonctionne un peu différemment, il ne commente pas une esperluette, vous pouvez donc l'utiliser comme commentaire en ligne.

echo First & REM. This is a comment & echo second

Mais pour éviter des problèmes avec des fichiers existants comme REM, REM.batou REM;.batseulement une variante modifiée doit être utilisée.

REM^;<space>Comment

Et pour le personnage ;est également autorisé l'un des;,:\/=

REM est environ 6 fois plus lent que ::(testé sur Win7SP1 avec 100000 lignes de commentaires).
Pour une utilisation normale ce n'est pas important (58µs contre 360µs par ligne de commentaire)

Commentaires avec ::

A exécute:: toujours un caret de fin de ligne.

:: This is also a comment^
echo This line is also a comment

Les étiquettes et également l' étiquette de commentaire :: ont une logique spéciale dans les blocs de parenthèses.
Ils s'étendent toujours sur deux lignes SO: la commande goto ne fonctionne pas .
Ils ne sont donc pas recommandés pour les blocs de parenthèses, car ils sont souvent la cause d'erreurs de syntaxe.

Avec ECHO ONune REMligne est affichée, mais pas une ligne commentée avec::

Les deux ne peuvent pas vraiment commenter le reste de la ligne, donc un simple %~provoquera une erreur de syntaxe.

REM This comment will result in an error %~ ...

Mais REM est capable d'arrêter l'analyseur par lots à un stade précoce, avant même que la phase des caractères spéciaux ne soit terminée.

@echo ON
REM This caret ^ is visible

Vous pouvez utiliser & REM ou & :: pour ajouter un commentaire à la fin de la ligne de commande. Cette approche fonctionne car «&» introduit une nouvelle commande sur la même ligne.

Commentaires avec des signes de pourcentage% = commentaire =%

Il existe un style de commentaire avec des signes de pourcentage.

En réalité, ce sont des variables mais elles sont étendues à rien.
Mais l'avantage est qu'ils peuvent être placés sur la même ligne, même sans &.
Le signe égal garantit qu'une telle variable ne peut pas exister.

echo Mytest
set "var=3"     %= This is a comment in the same line=%

Le style de pourcentage est recommandé pour les macros batch, car il ne modifie pas le comportement d'exécution, car le commentaire sera supprimé lorsque la macro sera définie.

set $test=(%\n%
%=Start of code=% ^
echo myMacro%\n%
)

Une autre alternative consiste à exprimer le commentaire comme une expansion variable qui ne se développe toujours à rien.

Les noms de variable ne peuvent pas contenir =, à l'exception des variables dynamiques non documentées comme
%=ExitCode%et %=C:%. Aucun nom de variable ne peut jamais contenir un =après la 1ère position. J'utilise donc parfois les éléments suivants pour inclure des commentaires dans un bloc entre parenthèses:

::This comment hack is not always safe within parentheses.
(
  %= This comment hack is always safe, even within parentheses =%
)

C'est aussi une bonne méthode pour incorporer des commentaires en ligne

dir junk >nul 2>&1 && %= If found =% echo found || %= else =% echo not found

Le début =n'est pas nécessaire, mais j'aime bien pour la symétrie.

Il existe deux restrictions:

1) le commentaire ne peut pas contenir %

2) le commentaire ne peut pas contenir :

Après avoir réalisé que je pouvais utiliser label ::pour faire des commentaires et commenter le code, cela REMme semblait tout simplement laid. A été mentionné que le double du côlon peut causer des problèmes lorsqu'ils sont utilisés à l' intérieur du ()code bloqué, mais j'ai découvert un travail autour en alternant entre les étiquettes ::et:space

:: This, of course, does
:: not cause errors.

(
  :: But
   : neither
  :: does
   : this.
)

Ce n'est pas laid comme REM, et ajoute en fait un peu de style à votre code.

Donc, en dehors des blocs de code que j'utilise ::et à l'intérieur, j'alterne entre ::et :.

Soit dit en passant, pour les gros morceaux de commentaires, comme dans l'en-tête de votre fichier de commandes, vous pouvez éviter complètement les commandes et les caractères spéciaux en simplement gotosur vos commentaires. Cela vous permet d'utiliser n'importe quelle méthode ou style de balisage que vous souhaitez, malgré le fait que si CMDjamais vous tentiez de traiter ces lignes, cela lancerait un sifflement.

@echo off
goto :TopOfCode

=======================================================================
COOLCODE.BAT

Useage:
  COOLCODE [/?] | [ [/a][/c:[##][a][b][c]] INPUTFILE OUTPUTFILE ]

Switches:
       /?    - This menu
       /a    - Some option
       /c:## - Where ## is which line number to begin the processing at.
         :a  - Some optional method of processing
         :b  - A third option for processing
         :c  - A forth option
  INPUTFILE  - The file to process.
  OUTPUTFILE - Store results here.

 Notes:
   Bla bla bla.

:TopOfCode
CODE
.
.
.

Utilisez la notation que vous souhaitez *, @etc.

Cette réponse tente un résumé pragmatique des nombreuses bonnes réponses sur cette page:

^{La grande réponse de jeb mérite une mention spéciale, car elle va vraiment en profondeur et couvre de nombreux cas de pointe.
Notamment, il souligne qu'une référence de variable / paramètre mal construite telle que %~peut casser l' une des solutions ci-dessous - y compris les REMlignes .}

Toute la ligne des commentaires - le style que directement pris en charge:

• REM(ou des variantes de cas) est la seule construction de commentaire officielle et est le choix le plus sûr - voir la réponse utile de Joey .

• ::est un hack (largement utilisé) , qui présente des avantages et des inconvénients :

  • Avantages :

    • Caractère distinctif visuel et, éventuellement, facilité de frappe.
    • La vitesse , bien que cela importera probablement rarement - voir la grande réponse de jeb et l'excellent article de blog de Rob van der Woude .

  • Inconvénients :

    • À l'intérieur des (...)blocs, ::peut casser la commande , et les règles pour une utilisation sûre sont restrictives et difficiles à retenir - voir ci-dessous.

Si vous ne souhaitez utiliser:: , vous avez ces choix:

• Soit : Pour être sûr, faites une exception à l'intérieur des (...)blocs et utilisez REM-les, ou ne placez pas de commentaires à l' intérieur (...) .
• Ou : mémorisez les règles douloureusement restrictives pour une utilisation sûre de l' ::intérieur(...) , qui sont résumées dans l'extrait de code suivant:

@echo off

for %%i in ("dummy loop") do (

  :: This works: ONE comment line only, followed by a DIFFERENT, NONBLANK line.
  date /t

  REM If you followed a :: line directly with another one, the *2nd* one
  REM would generate a spurious "The system cannot find the drive specified."
  REM error message and potentially execute commands inside the comment.
  REM In the following - commented-out - example, file "out.txt" would be
  REM created (as an empty file), and the ECHO command would execute.
  REM   :: 1st line
  REM   :: 2nd line > out.txt & echo HERE

  REM NOTE: If :: were used in the 2 cases explained below, the FOR statement
  REM would *break altogether*, reporting:
  REM  1st case: "The syntax of the command is incorrect."
  REM  2nd case: ") was unexpected at this time."

  REM Because the next line is *blank*, :: would NOT work here.

  REM Because this is the *last line* in the block, :: would NOT work here.
)

Émulation d' autres styles de commentaire - en ligne et multiligne:

Notez qu'aucun de ces styles n'est directement pris en charge par le langage batch , mais peut être émulé .

Commentaires en ligne :

<sup>* Les extraits de code ci-dessous servent verde remplaçant pour une commande arbitraire, afin de faciliter l'expérimentation.
* Pour que les SETcommandes fonctionnent correctement avec les commentaires en ligne, citez deux fois la name=valuepartie; par exemple SET "foo=bar". [1]</sup>

Dans ce contexte, nous pouvons distinguer deux sous-types:

• Commentaires EOL ([à la fin de la ligne]), qui peuvent être placés après une commande, et s'étendent invariablement jusqu'à la fin de la ligne (encore une fois, grâce à la réponse de jeb ):

  • ver & REM <comment>tire parti du fait qu'il REMs'agit d'une commande valide et &peut être utilisée pour placer une commande supplémentaire après une commande existante.
  • ver & :: <comment>fonctionne aussi, mais n'est vraiment utilisable qu'en dehors des (...)blocs , car son utilisation sûre y est encore plus limitée que l'utilisation ::autonome.

• Commentaires intra-ligne , qui doivent être placés entre plusieurs commandes sur une ligne ou idéalement même à l' intérieur d'une commande donnée.
  Les commentaires intra-ligne sont la forme la plus flexible (sur une seule ligne) et peuvent par définition également être utilisés comme commentaires EOL.

  • ver & REM^. ^<comment^> & verpermet d' insérer un commentaire entre les commandes (encore une fois, avec l'aimable autorisation de la réponse de jeb ), mais notez comment <et qu'il >fallait y ^échapper, car les caractères suivants. ne peut pas être utilisé tel< > | quel : (alors qu'il n'est pas échappé &ou &&ou ||démarrer la commande suivante ).

  • %= <comment> =%, comme détaillé dans la grande réponse de dbenham , est la forme la plus flexible , car elle peut être placée à l' intérieur d' une commande (parmi les arguments) .
    Il tire parti de la syntaxe d'expansion variable d'une manière qui garantit que l'expression se développe toujours dans la chaîne vide - tant que le texte du commentaire ne contient ni %ni:
    Like REM, %= <comment> =%fonctionne bien à la fois à l'extérieur et à l'intérieur des (...)blocs, mais il est plus distinctif visuellement; les seuls inconvénients sont qu'il est plus difficile à taper, plus facile à se tromper syntaxiquement, et peu connu, ce qui peut entraver la compréhension du code source qui utilise la technique.

Commentaires sur plusieurs lignes (bloc entier) :

• La réponse de James K montre comment utiliser une gotodéclaration et une étiquette pour délimiter un commentaire sur plusieurs lignes de longueur et de contenu arbitraires (qu'il utilise dans son cas pour stocker des informations d'utilisation).

• La réponse de Zee montre comment utiliser une "étiquette nulle" pour créer un commentaire sur plusieurs lignes, bien que des précautions doivent être prises pour terminer toutes les lignes intérieures avec ^.

• Le blog de Rob van der Woude mentionne une autre option quelque peu obscure qui vous permet de terminer un fichier avec un nombre arbitraire de lignes de commentaires : Une ouverture (ne fait que ignorer tout ce qui vient après , tant qu'elle ne contient pas de (non^-échappé)), c'est-à-dire tant que le bloc n'est pas fermé .

^{[1] Utiliser SET "foo=bar"pour définir des variables - c'est-à-dire mettre des guillemets doubles autour du nom et de =la valeur combinée - est nécessaire dans des commandes telles que SET "foo=bar" & REM Set foo to bar., afin de s'assurer que ce qui suit la valeur de variable voulue (jusqu'à la commande suivante, dans ce cas un seul espace) n'en fait pas accidentellement partie.
(En aparté: SET foo="bar"non seulement n'éviterait pas le problème, mais cela ferait des guillemets doubles une partie de la valeur ).
Notez que ce problème est inhérent SETet s'applique même aux espaces blancs de fin accidentels suivant la valeur, il est donc conseillé de toujours utiliser l' SET "foo=bar"approche.}

Cette page indique que l'utilisation de "::" sera plus rapide sous certaines contraintes Juste une chose à considérer lors du choix

bonne question ... Je recherche cette fonctionnalité depuis longtemps aussi ...

après plusieurs tests et astuces, il semble que la meilleure solution soit la plus évidente ...

-> le meilleur moyen que j'ai trouvé pour le faire, en empêchant l'échec de l'intégrité de l'analyseur, est de réutiliser REM:

echo this will show until the next REM &REM this will not show

vous pouvez également utiliser le multiligne avec l'astuce "NULL LABEL" ... (n'oubliez pas le ^ à la fin de la ligne pour la continuité)

::(^
this is a multiline^
comment... inside a null label!^
dont forget the ^caret at the end-of-line^
to assure continuity of text^ 
)

James K, je suis désolé d'avoir eu tort dans une bonne partie de ce que j'ai dit. Le test que j'ai fait était le suivant:

@ECHO OFF
(
  :: But
   : neither
  :: does
   : this
  :: also.
)

Cela correspond à votre description de l'alternance, mais échoue avec un ") était inattendu à ce moment." Message d'erreur.

J'ai fait des tests plus approfondis aujourd'hui et j'ai constaté que l'alternance n'est pas la clé, mais il semble que la clé ait un nombre pair de lignes, ne pas avoir deux lignes d'affilée commençant par des deux-points (: :) et ne se terminant pas par des deux-points . Considérer ce qui suit:

@ECHO OFF
(
   : But
   : neither
   : does
   : this
   : cause
   : problems.
)

Cela marche!

Mais considérez également ceci:

@ECHO OFF
(
   : Test1
   : Test2
   : Test3
   : Test4
   : Test5
   ECHO.
)

La règle d'avoir un nombre pair de commentaires ne semble pas s'appliquer lors de la fin d'une commande.

Malheureusement, c'est juste assez écureuil que je ne suis pas sûr de vouloir l'utiliser.

Vraiment, la meilleure solution, et la plus sûre à laquelle je peux penser, est de savoir si un programme comme Notepad ++ lirait REM en tant que deux-points, puis réécrirait les doubles-points en tant qu'instructions REM lorsque le fichier est enregistré. Mais je ne connais pas un tel programme et je ne connais aucun plugin pour Notepad ++ qui le fasse non plus.

Une discussion très détaillée et analytique sur le sujet est disponible sur CE page

Il a les exemples de codes et les avantages / inconvénients de différentes options.

Il existe plusieurs façons de commenter un fichier de commandes

1) Utilisation de rem

C'est la voie officielle. Il faut apparemment plus de temps pour exécuter que ::, bien que cela arrête apparemment l'analyse tôt, avant que les carets ne soient traités. L'expansion en pourcentage se produit avant rem et ::est identifiée, donc une utilisation en pourcentage incorrecte, c'est %~-à- dire provoquera des erreurs si des pourcentages sont présents. Sécuritaire à utiliser n'importe où dans les blocs de code.

2) L' utilisation d' étiquettes :, ::ou :;etc.

Pour :: comment, ': commentaire' est un nom d'étiquette non valide car il commence par un caractère non valide. Cependant, il est acceptable d'utiliser deux points au milieu d'une étiquette. Si un espace commence au début de l'étiquette, il est supprimé : labeldevient :label. Si un espace ou deux points apparaissent au milieu de l'étiquette, le reste du nom n'est pas interprété, ce qui signifie que s'il y a deux étiquettes :f:ooet :f rr, les deux seront interprétés comme :fet seule l'étiquette plus tard définie dans le fichier sera sautée. Le reste de l'étiquette est en fait un commentaire. Il existe plusieurs alternatives à ::, répertoriées ici . Vous ne pouvez jamais gotoou callune ::fooétiquette. goto :fooetgoto ::foo ne fonctionnera pas.

Ils fonctionnent bien en dehors des blocs de code mais après une étiquette dans un bloc de code, invalide ou non, il doit y avoir une ligne de commande valide. :: commentest en effet une autre commande valide. Il l'interprète comme une commande et non comme une étiquette; la commande a la priorité. Quelle est la commande pour cd vers le ::volume, qui fonctionnera si vous avez exécuté subst :: C:\, sinon vous obtenez une erreur de volume introuvable. C'est pourquoi :;est sans doute mieux car il ne peut pas être interprété de cette façon, et est donc interprété comme une étiquette à la place, qui sert de commande valide. Ce n'est pas récursif, c'est-à-dire que l'étiquette suivante n'a pas besoin d'une commande après elle. Voilà pourquoi ils viennent par deux.

Vous devez fournir une commande valide après l'étiquette, par exemple echo something. Une étiquette dans un bloc de code doit être accompagnée d'au moins une commande valide, de sorte que les lignes viennent par paires de deux. Vous obtiendrez une )erreur inattendue s'il y a un espace ou une parenthèse fermante sur la ligne suivante. S'il y a un espace entre les deux ::lignes, vous obtiendrez une erreur de syntaxe non valide.

Vous pouvez également utiliser l'opérateur caret dans le ::commentaire comme ceci:

@echo off

echo hello
(
   :;(^
   this^
   is^
   a^
   comment^
   )
   :;
)
   :;^
   this^
   is^
   a^
   comment
   :;
) 

Mais vous avez besoin du suivi :;pour la raison indiquée ci-dessus.

@echo off

(
echo hello
:;
:; comment
:; comment
:;
)
echo hello

C'est bien tant qu'il y a un nombre pair. C'est sans aucun doute la meilleure façon de commenter - avec 4 lignes et :;. Avec :;vous, aucune erreur ne doit être supprimée à l'aide de 2> nulou subst :: C:\. Vous pouvez utiliser subst :: C:\pour faire disparaître l'erreur de volume introuvable, mais cela signifie que vous devrez également mettre C: dans le code pour éviter que votre répertoire de travail ne devienne ::\.

Pour commenter à la fin d'une ligne, vous pouvez faire command &::ou command & rem comment, mais il doit toujours y avoir un nombre pair, comme ceci:

@echo off

(
echo hello & :;yes
echo hello & :;yes
:;
)

echo hello

Le premier echo hello & :;yesa une commande valide sur la ligne suivante, mais pas le second & :;yes, il en a donc besoin, c'est-à-dire le :;.

3) Utilisation d'une variable d'environnement non valide

%= comment =%. Dans un fichier de commandes, les variables d'environnement non définies sont supprimées du script. Cela permet de les utiliser en fin de ligne sans utiliser &. Il est personnalisé d'utiliser une variable d'environnement non valide, c'est-à-dire qui contient un signe égal. L'égalité supplémentaire n'est pas requise mais donne un aspect symétrique. De plus, les noms de variables commençant par "=" sont réservés aux variables dynamiques non documentées. Ces variables dynamiques ne se terminent jamais par "=", donc en utilisant un "=" au début et à la fin du commentaire, il n'y a aucune possibilité de conflit de nom. Le commentaire ne peut pas contenir %ou :.

@echo off 
echo This is an example of an %= Inline Comment =% in the middle of a line.

4) En tant que commande, rediriger stderr vers nul

@echo off
(
echo hello
;this is a comment 2> nul
;this is another comment  2> nul
)

5) À la fin d'un fichier, tout ce qui se trouve après une parenthèse non fermée est un commentaire

@echo off
(
echo hello
)

(this is a comment
this is a comment
this is a comment