Using Comments as a Debugging Aid

  • Article

Microsoft® Windows® 2000 Scripting Guide

If you have ever written a lengthy report or memorandum, you might have found it useful to type notes to yourself as you worked on the document. For example, you might have typed something such as, "Need to add a section here about the budget problems from a year ago" or "These two paragraphs need to be rewritten." Notes such as these are useful reminders and also serve as a sort of status report, letting you know what is and is not working, and how you are progressing.

Comments allow you to put this same type of status report in scripts still in development. For example, suppose you are working on a script and you encounter a problem. If you are unable to immediately solve the problem, insert a comment labeled BUG to indicate that this section of code needs further work. The next time you work on that script, search for BUG to locate any sections of the code that are not working properly. If you are able to fix the problem, remove the BUG comment.

For example, you might use the following comment labels:

  • BUG. Indicates code that is not working correctly.

  • INCOMPLETE. Indicates code that is not yet finished.

  • PERFORMANCE. Indicates code that works but whose performance might be improved.

  • REVIEW. Indicates lines of code that need further review to ensure they are working correctly.

The following script snippet illustrates comments used as a debugging aid.

'* BUG (DMS 3/10/02)     This should loop through all 100 sales districts,
'* BUG (DMS 3/10/02)     calling the function RetrieveInformation for each one,
'* BUG (DMS 3/10/02)     but it only does the first 90 sales districts and then
'* BUG (DMS 3/10/02)     stops.

For i = 1 to 100
    RetrieveInformation(i)
Next

The debugging comments in the preceding snippet include the reviewer's initials and the date the comment was added. This facilitates communication between the script writer and the reviewer. In addition, it helps ensure that no unneeded comments are left in the finished code; a debugging comment added years earlier is unlikely to still be valid and should be deleted.

Removing Debugging Comments

To ensure that you remove all debugging comments from a script, you can use a second script to remove them. The script shown in Listing 18.3 removes debugging comments by doing the following:

  • Opens the script C:\Scripts\CreateUser.vbs.

  • Reads each line in the file and checks for the presence of the string '* BUG anywhere in the line. If the string is found, the line is discarded as a debugging comment. If the string is not found, the line is retained as part of the variable strSavedLines.

  • Overwrites the existing version of the script using the variable strSavedLines, which contains all the non-debug lines in the script.

Listing 18.3 Removing Debugging Comments

   
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

Const ForReading = 1
Const ForWriting = 2
Set objFSO = CreateObject("Scripting.FileSystemObject")
Set objTextFile = objFSO.OpenTextFile("C:\Scripts\CreateUser.vbs", ForReading)
Do While objTextFile.AtEndOfStream <> true
 strNextLine = objTextFile.Readline
 intCheckForBugComment = Instr(strNextLine, "'* BUG")
 If intCheckForBugComment = 0 Then
 strSavedLines = strSavedLines & strNextLine & VbCrLf
 End If
Loop
Set objTextFile = objFSO.OpenTextFile _
 ("c:\scripts\CreateUser.vbs" , ForWriting)
objTextFile.Write strSavedLines
objTextFile.Close