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.
This means each comment line causes one extra reread of the batch file; no problem when read from harddisk, but it may slow down batch file execution from slow floppy or network drives.

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, whether 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.

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

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
)

(
	REM comment1
	ECHO comment1
)

(REM comment2 & ECHO comment2)

REM comment3 & ECHO comment3

ECHO comment4

D:\>test_REM_comments_in_code_blocks.bat

D:\>(
REM comment1
 ECHO comment1
)
comment1
D:\>
D:\>

More information on the subject:

• Michael Klement's summary of a discussion on comment styles on StackOverflow.com
  You will find even more comment styles here (like %= inline comments =%), each with its own list of pros and cons
• A discussion about double colons vs. REM
• Batch comments

(Thanks for Lee Wilbur and Michael Klement)

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 CMD.EXE (Windows NT 4 and later) the line is completely ignored (as was probably intended), but COMMAND.COM (MS-DOS, 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; there is no guarantee they will still work in future Windows versions
• 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; though leading whitespace is allowed, nothing else is
• using double colons inside code blocks violates the previous "rule" and will usually result in errors (except some special cases)
• try to avoid comments inside code blocks, or use REM if you have to (but be aware of pitfalls if you do use REM)
• with COMMAND.COM be careful when using either REM or double colons to temporarily "disable" a command line, especially when it contains piping, redirection or variables
• despite 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, on all Windows versions they will be used for

Pipe REM to block Standard Input

A really useful trick is to 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)

Comment blocks

Several languages allow complete code blocks to be commented out by using /* and */ "tags".
Rexx, for example, will treat the whole text marked red as comment:

Say "This line is true code"

/*
But this line is comment.
And so is this line.
And this one...
*/

The batch language doesn't have comment blocks, though there are ways to accomplish the effect:

@ECHO OFF
REM Do something
  •
  •
REM End of code

REM Start of comment block 1
GOTO EndComment1
This line is comment.
And so is this line.
And this one...
:EndComment1

Or, if the comment block appears at the end of the batch file:

@ECHO OFF
REM Do something
  •
  •
REM End of code; use GOTO:EOF instead of EXIT for Windows NT and later
EXIT

Start of comment block at end of batch file
This line is comment.
And so is this line.
And this one...

Leo Gutierrez Ramirez came up with an even shorter way to accomplish a comment block at the end of a batch file:

@ECHO OFF
REM Do something
  •
  •
REM End of code

(Start of comment block at end of batch file
This line is comment.
And so is this line.
And this one...
Just make sure you never use a closing parenthesis.

(REM comment2 & ECHO comment2)

(REM whatever