Batch file commenting

[nchernoff]

Migrated From JP Software Wiki

This article describes "quick and dirty" methods of commenting batch files.

Colons

Batch file line labels begin with a colon. If the colon is followed by two spaces, the command processor simply ignores the entire line. It is not treated as a line label and it also does not generate a syntax error.

:  To create a neat comment block quickly, simply
:  begin each line with a colon followed by at least
:  two spaces.

:  As usual, blank lines won't cause a problem.

Text -- Endtext block

A large "comment block" can be inserted between TEXT -- ENDTEXT commands that are never called. In the example one block is skipped with GOTO and the other is after a subroutine. The reason TEXT -- ENDTEXT is necessary is because if you just use GOTO the command processor may interpret the comment text as command lines and generate a syntax error.

An advantage to this method is that if you need printed instructions you can put them in the TEXT -- ENDTEXT block and to display them copy the file and simply make the first line of the copy GOTO LONG_COMMENT. Note that the Pause and Quit are inside the comment although after the ENDTEXT, so in normal operation they have no effect.

Alternatively, you could make the first or second line IF "%1"=="comments" GOTO LONG_COMMENT. (Note: All the double quotes are necessary and there are two equal signs, not one.) If you want to display the LONG_COMMENT section only, you run the batch file with the command-line parameter "comments".

IF SOMETHING (WHATEVER)
GOSUB SOME_SUB

GOTO AFTER_COMMENT

:LONG_COMMENT
TEXT
 Whatever you want here.
ENDTEXT
PAUSE
QUIT

:AFTER_COMMENT
ECHO SOMETHING
RETURN (or QUIT or EXIT)

:SOME_SUB
(subroutine code)
RETURN

TEXT

Whatever you want here as "comments".

ENDTEXT

 

[Rick Reinckens]

I just tried the "multiple spaces" in TCC/LE 13 and it doesn't work. I tried 1, 2 and 3 spaces and the processor recognized all of them as labels.

Here's the code I used:

@echo off
echo Hello
Goto Test_Skip
echo Goodbye
: Test_Skip
echo Done​

I haven't tried 4 spaces, but with 1, 2, 3 or a tab it prints Hello and Done. If you put a colon in front of the Goto it prints Hello, Goodbye and Done.

I also tried this:

@echo off
echo Hello
Goto Test_Skip
echo Goodbye
:: Test_Skip
echo Done​

That prints Hello and then generates the error: Label Not Found "Test_Skip"
If the space between the double colons and the text is removed it generates the same error.

So, it looks like a way that will work is double colons to start a line -- and that has the advantage of making comments clearly distinguishable from labels.

 

[Rodolfo]

I am not sure I understand, are there any issues with REM?

Regards

Rodolfo Giovanninetti

 

[Rick Reinckens]

No issues with REM.

The initial post in this thread is actually For block comments, most folks don't want a bunch of REM statements, they want something that stands out. The original post in this thread is actually based on an article I had posted when JP had a wiki. Apparently the "colon{space}{space}" method worked back then but not now.

 

[Rick Reinckens]

CAUTION WITH DO -- ENDDO LOOPS

There is one caution with DO -- ENDDO loops. The initial suggestion mentions using TEXT -- ENDTEXT and a GOTO to jump around that. If you put a GOTO inside a DO loop, even if the target label is inside the DO loop it will cause the loop to end.

 

[Charles Dye]

CAUTION WITH DO -- ENDDO LOOPS

There is one caution with DO -- ENDDO loops. The initial suggestion mentions using TEXT -- ENDTEXT and a GOTO to jump around that. If you put a GOTO inside a DO loop, even if the target label is inside the DO loop it will cause the loop to end.

See the help file for GOTO's /I option, which prevents GOTO from popping IFFs and DOs off the stack.