Adding Comments to Scripts

Adding Comments to Scripts

Comments 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 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
    
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 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.