Which comment style should I use in batch files

Question

I ve been writing some batch files  and I ran into this user guide  which has been quite informative  One thing it showed me was that lines can be commented not just with REM  but also with     It says      Comments in batch code can be made by using a double-colon  this is better than using the REM command because labels are processed before redirection symbols     lt remark gt  causes no problems but rem  lt remark gt  produces errors     Why then  do most guides and examples I see use the REM command  Does    work on all versions of Windows

User · Accepted Answer

tl dr  REM is the documented and supported way to embed comments in batch files        is essentially a blank label that can never be jumped to  whereas REM is an actual command that just does nothing  In neither case  at least on Windows 7  does the presence of redirection operators cause a problem   However     is known to misbehave in blocks under certain circumstances  being parsed not as a label but as some sort of drive letter  I m a little fuzzy on where exactly but that alone is enough to make me use REM exclusively  It s the documented and supported way to embed comments in batch files whereas    is merely an artifact of a particular implementation     Here is an example where    produces a problem in a FOR loop   This example will not work in a file called test bat on your desktop    echo off for  F  delims     A in   type C  Users  username  Desktop test bat   do         echo hello gt C  Users  username  Desktop text txt   pause   While this example will work as a comment correctly    echo off for  F  delims     A in   type C  Users  username  Desktop test bat   do       REM echo hello gt C  Users  username  Desktop text txt   pause   The problem appears to be when trying to redirect output into a file  My best guess is that it is interpreting    as an escaped label called  echo

User · Answer

A very detailed and analytic discussion on the topic is available on THIS page  It has the example codes and the pros cons of different options

User · Answer

This answer attempts a pragmatic summary of the many great answers on this page   jeb s great answer deserves special mention  because it really goes in-depth and covers many edge cases  Notably  he points out that a misconstructed variable parameter reference such as    can break any of the solutions below - including REM lines     Whole-line comments - the only directly supported style    REM  or case variations thereof  is the only official comment construct  and is the safest choice - see Joey s helpful answer     is a  widely used  hack  which has pros and cons    Pros    Visual distinctiveness and  possibly  ease of typing  Speed  although that will probably rarely matter - see jeb s great answer and Rob van der Woude s excellent blog post   Cons    Inside       blocks     can break the command  and the rules for safe use are restrictive and not easy to remember - see below        If you do want to use     you have these choices    Either  To be safe  make an exception inside       blocks and use REM there  or do not place comments inside       altogether  Or  Memorize the painfully restrictive rules for safe use of    inside        which are summarized in the following snippet       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  gt  out txt  amp  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        Emulation of other comment styles - inline and multi-line   Note that none of these styles are directly supported by the batch language  but can be emulated     Inline comments      The code snippets below use ver as a stand-in for an arbitrary command  so as to facilitate experimentation    To make SET commands work correctly with inline comments  double-quote the name value part  e g   SET  foo bar   1    In this context we can distinguish two subtypes    EOL comments   to-the- end-of-line   which  can be placed after a command  and invariably extend to the end of the line  again  courtesy of jeb s answer     ver  amp  REM  lt comment gt  takes advantage of the fact that REM is a valid command and  amp  can be used to place an additional command after an existing one  ver  amp      lt comment gt  works too  but is really only usable outside of       blocks  because its safe use there is even more limited than using    standalone   Intra-line comments  which be placed between multiple commands on a line or ideally even inside of a given command  Intra-line comments are the most flexible  single-line  form and can by definition also be used as EOL comments    ver  amp  REM     lt comment  gt   amp  ver allows inserting a comment between commands  again  courtesy of jeb s answer   but note how  lt  and  gt  needed to be  -escaped  because the following chars  cannot be used as-is   lt   gt     whereas unescaped  amp  or  amp  amp  or    start the next command       lt comment gt      as detailed in dbenham s great answer  is the most flexible form  because it can be placed inside a command  among the arguments   It takes advantage of variable-expansion syntax in a way that ensures that the expression always expands to the empty string - as long as the comment text contains neither   nor   Like REM      lt comment gt     works well both outside and inside       blocks  but it is more visually distinctive  the only down-sides are that it is harder to type  easier to get wrong syntactically  and not widely known  which can hinder understanding of source code that uses the technique       Multi-line  whole-line block  comments    James K s answer shows how to use a goto statement and a label to delimit a multi-line comment of arbitrary length and content  which in his case he uses to store usage information   Zee s answer shows how to use a  null label  to create a multi-line comment  although care must be taken to terminate all interior lines with    Rob van der Woude s blog post mentions another somewhat obscure option that allows you to end a file with an arbitrary number of comment lines  An opening   only causes everything that comes after to be ignored  as long as it doesn t contain a   non- -escaped     i e   as long as the block is not closed       1  Using SET  foo bar  to define variables - i e   putting double quotes around the name and   and the value combined - is necessary in commands such as SET  foo bar   amp  REM Set foo to bar   so as to ensure that what follows the intended variable value  up to the next command  in this case a single space  doesn t accidentally become part of it   As an aside  SET foo  bar  would not only not avoid the problem  it would make the double quotes part of the value   Note that this problem is inherent to SET and even applies to accidental trailing whitespace following the value  so it is advisable to always use the SET  foo bar  approach

User · Answer

good question    I ve been looking for this functionality for long too     after several tests and tricks it seem the better solution is the more obvious one     --  best way I found to do it  preventing parser integrity fail  is reusing REM   echo this will show until the next REM  amp REM this will not show   you can also use multiline with the  NULL LABEL  trick      dont forget the   at the end of the line for continuity        this is a multiline  comment    inside a null label   dont forget the  caret at the end-of-line  to assure continuity of text

User · Answer

This page tell that using      will be faster under certain constraints Just a thing to consider when choosing

User · Answer

After I realized that I could use label    to make comments and comment out code REM just looked plain ugly to me  As has been mentioned the double-colon can cause problems when used inside    blocked code  but I ve discovered a work-around by alternating between the labels    and  space     This  of course  does    not cause errors          But      neither      does      this      It s not ugly like REM  and actually adds a little style to your code   So outside of code blocks I use    and inside them I alternate between    and     By the way  for large hunks of comments  like in the header of your batch file  you can avoid special commands and characters completely by simply gotoing over your comments   This let s you use any method or style of markup you want  despite that fact that if CMD ever actually tried to processes those lines it d throw a hissy    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         Use what ever notation you wish   s    s etc

User · Answer

Another alternative is to express the comment as a variable expansion that always expands to nothing   Variable names cannot contain    except for undocumented dynamic variables like   ExitCode  and   C    No variable name can ever contain an   after the 1st position  So I sometimes use the following to include comments within a parenthesized block     This comment hack is not always safe within parentheses         This comment hack is always safe  even within parentheses        It is also a good method for incorporating in-line comments  dir junk  gt nul 2 gt  amp 1  amp  amp     If found    echo found       else    echo not found   The leading   is not necessary  but I like if for the symmetry   There are two restrictions    1  the comment cannot contain    2  the comment cannot contain

User · Answer

There are a number of ways to comment in a batch file  1 Using rem  This is the official way  It apparently takes longer to execute than     although it apparently stops parsing early  before the carets are processed  Percent expansion happens before rem and    are identified  so incorrect percent usage i e     will cause errors if percents are present  Safe to use anywhere in code blocks   2 Using labels       or    etc   For    comment     comment  is an invalid label name because it begins with an invalid character  It is okay to use a colon in the middle of a label though  If a space begins at the start of label  it is removed   label becomes  label  If a space or a colon appears in the middle of the label  the rest of the name is not interpreted meaning that if there are two labels  f oo and  f rr  both will be interpreted as  f and only the later defined label in the file will be jumped to  The rest of the label is effectively a comment  There are multiple alternatives to     listed here  You can never goto or call a   foo label  goto  foo and goto   foo will not work   They work fine outside of code blocks but after a label in a code block  invalid or not  there has to be a valid command line     comment is indeed another valid command  It interprets it as a command and not a label  the command has precedence  Which is the command to cd to the    volume  which will work if you have executed subst    C    otherwise you get a cannot find the volume error  That s why    is arguably better because it cannot be interpreted in this way  and therefore is interpreted as a label instead  which serves as the valid command  This is not recursive  i e  the next label does not need a command after it  That s why they come in twos   You need to provide a valid command after the label e g  echo something  A label in a code block has to come with at least one valid command  so the lines come in pairs of two  You will get an unexpected   error if there is a space or a closing parenthesis on the next line  If there is a space between the two    lines you will get an invalid syntax error   You can also use the caret operator in the    comment like so    echo off  echo hello              this     is     a     comment                         this     is     a     comment            But you need the trailing    for the reason stated above    echo off    echo hello       comment    comment      echo hello    It is fine as long as there is an even number  This is undoubtedly the best way to comment -- with 4 lines and     With    you don t get any errors that need to be suppressed using 2 gt  nul or subst    C    You could use subst    C   to make the volume not found error go away but it means you will have to also put C  in the code to prevent your working directory from becoming       To comment at the end of a line you can do command  amp    or command  amp  rem comment  but there still has to be an even number  like so    echo off    echo hello  amp    yes echo hello  amp    yes       echo hello   The first echo hello  amp    yes has a valid command on the next line but the second  amp    yes does not  so it needs one i e  the      3 Using an invalid environment variable     comment     In a batch file  environment variables that are not defined are removed from the script  This makes it possible to use them at the end of a line without using  amp   It is custom to use an invalid environment variable i e  one that contains an equals sign  The extra equals is not required but makes it look symmetrical  Also  variable names starting with     are reserved for undocumented dynamic variables  Those dynamic variables never end with      so by using an     at both the start and end of the comment  there is no possibility of a name clash  The comment cannot contain   or      echo off  echo This is an example of an    Inline Comment    in the middle of a line    4 As a command  redirecting stderr to nul   echo off   echo hello  this is a comment 2 gt  nul  this is another comment  2 gt  nul     5 At the end of a file  everything after an unclosed parenthesis is a comment   echo off   echo hello     this is a comment this is a comment this is a comment

User · Answer

Comments with REM  A REM can remark a complete line  also a multiline caret at the line end  if it s not the end of the first token     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 followed by some characters       works a bit different  it doesn t comment an ampersand  so you can use it as inline comment   echo First  amp  REM  This is a comment  amp  echo second   But to avoid problems with existing files like REM  REM bat or REM  bat only a modified variant should be used   REM   lt space gt Comment   And for the character   is also allowed one of         REM is about 6 times slower than     tested on Win7SP1 with 100000 comment lines   For a normal usage it s not important  58  s versus 360  s per comment line   Comments with     A    always executes a line end caret      This is also a comment  echo This line is also a comment   Labels and also the comment label    have a special logic in parenthesis blocks  They span always two lines SO  goto command not working  So they are not recommended for parenthesis blocks  as they are often the cause for syntax errors   With ECHO ON a REM line is shown  but not a line commented with     Both can t really comment out the rest of the line  so a simple    will cause a syntax error     REM This comment will result in an error          But REM is able to stop the batch parser at an early phase  even before the special character phase is done    echo ON REM This caret   is visible   You can use  amp REM or  amp    to add a comment to the end of command line  This approach works because   amp   introduces a new command on the same line   Comments with percent signs     comment     There exists a comment style with percent signs     In reality these are variables but they are expanded to nothing  But the advantage is that they can be placed in the same line  even without  amp   The equal sign ensures  that such a variable can t exists     echo Mytest set  var 3         This is a comment in the same line     The percent style is recommended for batch macros  as it doesn t change the runtime behaviour  as the comment will be removed when the macro is defined   set  test    n    Start of code     echo myMacro  n

User · Answer

James K  I m sorry I was wrong in a fair portion of what I said   The test I did was the following    ECHO OFF        But      neither      does      this      also      This meets your description of alternating but fails with a    was unexpected at this time   error message     I did some farther testing today and found that alternating isn t the key but it appears the key is having an even number of lines  not having any two lines in a row starting with double colons      and not ending in double colons  Consider the following    ECHO OFF        But      neither      does      this      cause      problems      This works     But also consider this    ECHO OFF        Test1      Test2      Test3      Test4      Test5    ECHO      The rule of having an even number of comments doesn t seems to apply when ending in a command   Unfortunately this is just squirrelly enough that I m not sure I want to use it     Really  the best solution  and the safest that I can think of  is if a program like Notepad   would read REM as double colons and then would write double colons back as REM statements when the file is saved   But I m not aware of such a program and I m not aware of any plugins for Notepad   that does that either

[batch-file] Which comment style should I use in batch files?

Examples related to batch-file

Examples related to coding-style

Examples related to comments