Adding Comments

7/27/2019 Adding Comments

1/4

Adding Comments to ScriptsComments are statements that are ignored by the script host when the

script runs.

To ensure that the script host does not attempt to interpret a comment as a

command, we must preface each comment with a comment delimiter.

VBScript allows two delimiters: the single quotation mark (') and the REM

statement.

For example, both of the following lines of code are valid comments:

' This is a comment using a single quote delimiter.

REM This is a comment using the REM statement as a delimiter.

Although most script writers use the single quotation mark, you might

consider following the single quotation mark with an asterisk when

commenting your code:

'* This is another comment.

This approach has two advantages over the single quotation mark alone.

First, it makes the comment stand out from the rest of the text; a single

quotation mark by itself can be difficult to see at times.

Second, the single quotation mark is a valid VBScript character that has uses

beyond delimiting comments.

This can be a problem if we use an automated procedure to extract

comments from a script; such a procedure might also retrieve items that are

not comments. Because we are less likely to use '* anywhere else in our

script, it makes a good delimiter.

Always include comments on separate lines except for comments that


2/4

accompany the declaration of a variable.

Comments included on the same line as a VBScript statement (end-of-the-

line comments) are valid but can be difficult to read.

For example, compare the two commenting styles in the following script

snippet; in the first half of the script, comments are placed on the same line

as a VBScript statement, while in the second half of the script, the

comments are placed on separate lines.

Most people find it easier to quickly identify the comments used in the

second half of the script.

----------------------------------------------- On Error Resume Next

Set WshNetwork = WScript.CreateObject("WScript.Network")

WshNetwork.MapNetworkDrive "Z:", "\\RemoteServer\Public" '* Map drive

Z.

If Err.Number 0 Then '* Check to make sure the operation succeeded.

Err.Clear

Wscript.Echo "The drive could not be mapped."

End If

'* Map drive Z.

WshNetwork.MapNetworkDrive "Z:", "\\RemoteServer\Public"

'* Check to make sure the operation succeeded.

If Err.Number 0 Then

Err.Clear


3/4

Wscript.Echo "The drive could not be mapped."

End If-----------------------------------------------

Code Commenting Conventions

All procedures should begin with a brief comment describing what they do.

This description should not describe the implementation details (how it does

it) because these often change over time, resulting in unnecessary comment

maintenance work, or worse, erroneous comments.

The code itself and any necessary inline comments describe the

implementation.

Arguments passed to a procedure should be described when their purpose is

not obvious and when the procedure expects the arguments to be in a

specific range.

Return values for functions and variables that are changed by a procedure,

especially through reference arguments, should also be described at the

beginning of each procedure.

Procedure header comments should include the following section headings.

Section Heading:

Comment Contents:

Purpose:

Assumptions:

Remember the following points:

Every important variable declaration should include an inline comment


4/4

describing the use of the variable being declared.

Variables, controls, and procedures should be named clearly to ensure that

inline comments are only needed for complex implementation details.

At the beginning of your script, you should include an overview that

describes the script, enumerating objects, procedures, algorithms, dialog

boxes, and other system dependencies. Sometimes a piece of pseudocode

describing the algorithm can be helpful.

Documents

Adding Comments