Comments

Regardless of the programming or scripting language used, it is always a good idea to insert comments in scripts, explaining what the next lines or block of code is trying to accomplish, how and/or why.

Comments in batch files are usually placed in lines starting with REM (REMarks).

If you have many lines REMed out, this may slow down COMMAND.COM's processing of the batch file.

As you probably know, COMMAND.COM reads a batch file, executes one command line, reads the batch file again, executes the next command line, etcetera.

A workaround I have seen many times (back in the old days, when I was young, and dinosaurs roamed the Earth and harddisks were 20MB) is to convert the comment line to a label by starting the line with a colon ( : ).
COMMAND.COM skips labels it doesn't have to jump to.

This method has the disadvantage that your batch file may "accidently" really use the label to jump to.

As Marc Stern points out in one of his MS-DOS batch files Tips & Tricks, this can be solved by using a double colon ( :: ) as the first characters of the comment line.
That way, the label is invalid but still treated as a label, and skipped (i.e. the next line is read immediately by COMMAND.COM, without the need to reopen the batch file). This may speed up reading large blocks of comment lines from slow (floppy) drives.

This same trick works in CMD.EXE (the command processor in Windows NT 4 and later) as well (not sure about OS/2 though)...

...but with some restrictions!

REM is a true command that may be used anywhere within a command line.
Though I doubt there is much use for a command like:

IF EXIST C:\AUTOEXEC.BAT REM AUTOEXEC.BAT exists

it is valid and won't generate an error message in any DOS or Windows version.

Labels, on the other hand, wether valid or not, should always start at the first non-whitespace character in a command line.

REM Comment line 1
    REM Comment line 2
:Label1
    :Label2
:: Comment line 3
    :: Comment line 4
IF EXIST C:\AUTOEXEC.BAT REM AUTOEXEC.BAT exists

are all allowed.
However,

IF EXIST C:\AUTOEXEC.BAT :: AUTOEXEC.BAT exists

will result in a Syntax error message.

A true pitfall are code blocks, several commands grouped between parentheses and interpreted as a single command line by CMD.EXE!

IF EXIST C:\AUTOEXEC.BAT (
    :: Comment line 1
    ECHO Do something
    :: Comment line 2
)

will result in an error message stating:

) was unexpected at this time.

and:

IF EXIST C:\AUTOEXEC.BAT (
    :: Comment line 1
    ECHO Do something
    :: Comment line 2
    :: Comment line 3
)

will result in another error message:

Do something
The system cannot find the drive specified.

The same is true for FOR loops.
Try and see for yourself:

FOR %%A IN (1 2 3) DO (
    :: Comment line 1
    ECHO Do something
    :: Comment line 2
)

and:

FOR %%A IN (1 2 3) DO (
    :: Comment line 1
    ECHO Do something
    :: Comment line 2
    :: Comment line 3
)

will also result in error messages.

The errors are caused by labels being used within code blocks.
Replace the double colons by REM statements and these samples will all run without a glitch.
Better still, don't use comments within code blocks at all, but place them just before the code blocks instead:

:: Comment line 1
:: Comment line 2
:: Comment line 3
FOR %%A IN (1 2 3) DO (
    ECHO Do something
)

or:

REM Comment line 1
REM Comment line 2
REM Comment line 3
FOR %%A IN (1 2 3) DO (
    ECHO Do something
)

More information on the subject:

• A discussion about double colons vs. REM
• Batch comments

(Thanks for Lee Wilbur)

A possible pitfall, pointed out by Joost Kop, is a REM to comment out a line that uses redirection, as in:

REM DIR > logfile.log

In Windows 2000 the line is completely ignored (as was probably intended), but Windows 9x interprets this line as "redirect the output of REM to logfile.log", thus emptying the file logfile.log or creating a 0 bytes file logfile.log.

Summarizing:

• REM is the standards-compliant, documented statement to insert comments in batch files
• double colons are a non-documented and non-compliant way to insert comments
• in theory, using double colons may speed up execution of batch files when run from a slow disk drive (e.g. floppy disk), but I doubt the difference can be detected on modern computers
• for large blocks of comment, a GOTO command just before the comments, jumping to a label just after the comments, is a safer and more standards-compliant way to speed up batch execution from slow drives
• since double colons are actually labels, they should be placed at the start of a command line; leading whitespace is allowed, nothing else is
• using double quotes inside code blocks violates the previous "rule" and will result in errors
• try to avoid comments inside code blocks, or use REM if you have to
• be careful when using either REM or double colons to temporarily "disable" a command line, especially when it contains piping, redirection or variables
• depite all, there is nothing wrong with using double colons for comments as long as you understand the limitations
• test, test, test and test your batch files, including comment lines

Pipe REM to block Standard Input

A really useful trick is to use use REM combined with piping, as in:

REM | CHOICE /C:AB /T:A,5 > NUL

The CHOICE command in itself would time out after 5 seconds (/T), except if someone presses a key not specified by /C, in which case the count down would be aborted.
By using REM and piping its (always empty) standard output to CHOICE's standard input, this standard input will not receive keypresses from the console (keyboard) anymore. So pressing a button neither speeds up CHOICE nor stops it.
(I borrowed this technique from "Outsider", one of the alt.msdos.batch newsgroup's "regulars", and added the /C parameter to make it language independent)