Commenting Scripts

Microsoft® Windows® 2000 Scripting Guide

Comments provide clarification or additional information about a script and the script's purpose. Comments serve a function similar to that of a narrator in a movie: The narrator tells you what the characters in the movie are thinking; comments tell you what the script writer was thinking when he or she wrote the code. Without comments, readers must guess at the script's purpose and why it uses one approach rather than another. Comments improve a reader's understanding of the script.

It is generally a good idea to comment all scripts except scripts that are used once and then discarded. At a minimum, you should comment the following:

• The script itself, in the form of a script header.

• Procedures and functions.

• Large control structures that are not part of a procedure or function. For example, if your script connects to a directory service, comment the section of the script where you actually connect to the directory service, even if it is not encapsulated in a function or procedure.

• Any line of the script that needs clarification. When in doubt, it is better that a script have too many comments than too few.

Adding comments

A good narrator tries to avoid the obvious and to tell you only what you might not be able to determine for yourself. If the main character in a movie is seen walking along a river, the narrator will rarely say something like, "And then the main character walked along the river." Instead, the narrator might tell you why the main character is walking along the river, but only if the reason behind this might not be obvious, and only if this narration helps to clarify what is happening.

Comments should be added only in similar circumstances; that is, only if the reason for using the code is not obvious, and only if the comment helps clarify what happens within the script. You might consider these guidelines when adding comments to a script:

• Comments should describe the general purpose of the script. Comments need not provide a step-by step description of what happens in the script and should not provide a primer in scripting; someone who does not understand what the Wscript.Echo method does should not be editing your script. Reserve comments for those items that need further clarification. Commenting every statement leads to two problems. First, you need to write the script twice - once for each statement and again for each comment. Second, you risk obscuring the important comments if you include too many unneeded comments. The following type of comment should be avoided:

  ' Echo the date
  Wscript.Echo Date
  

  In addition, be careful not to editorialize when commenting the code. Comments should explain what the code does, not offer judgments as to the quality of that code. Raise quality issues in a different forum. The following type of comment does little to assure the reader that this is a script worth running:

  ' Echo the date even though it seems silly to echo the date at this point
  Wscript.Echo Date
  

• Comments are not a solution for a poorly constructed script. If a section of your script is too complicated to summarize in a few sentences, consider rewriting that section. As a general rule, well-written code requires minimal commenting. If you find yourself having to explain over and over why you wrote a particular section of code in a particular way, you might stop and think about whether there is a better way to carry out the same function.

• Use complete sentences, and proofread for spelling and grammar. Do not add terse and cryptic comments to your code. A comment such as "Get user info" adds no value. Instead, use a comment that gives the reader useful information. The following comment makes it clear user information is being retrieved:

  '    Retrieve the account name, department, and job title for each user.
  

  You should also ensure that comments are grammatically correct and spelled correctly. Poor grammar and spelling not only make the code harder to read, but do little to inspire confidence in your professionalism, and to offer assurance that the code has been properly checked and tested.

• Write comments as you write the script. Although it is customary to write comments after the code is complete, this approach can lead to the following problems:

  • Finding time to go back and add the comments is difficult. After a script is working, it is usually more important to begin using that script than it is to delay its implementation while you add comments. If you save comments until the end, you are less likely to add them.

  • You might forget what the code does. Comments not only help other people understand your code, they also help you understand your own code. For example, if you copy a procedure from another source and fail to comment it, you might not remember what the procedure does, and why you included it.

  • Comments added after a script is written are often included as an afterthought and do little to improve the readability of the script. Comments that do not enhance the clarity of the code can be worse than no comments; they can be a distraction to anyone trying to read and understand the script.

  Interestingly enough, some script writers actually write comments before writing code. This enables them to record their thoughts and forces them to construct a logical flow for the program before writing code on a line-by-line basis.

• Comments should not contradict the script. Because comments clarify your script, ensure that the comments and the script do not conflict. For example, the following script snippet reveals a conflict between the comments and the script itself. According to the script, the variable strUserLocationIdentifier is based on the user's home state; according to the comments, however, the value of this variable is based on the users home city:

  '* Set the location identifier for the user based on the user's home city
  If strUserHomeState = "WA" Then
      strUserLocationIdentifier = "Local"
  Else
      strUserLocationIdentifier = "Off-site"
  End If
  

  Contradictions like this often occur when a section of a script is modified but the accompanying comments are not. Any time you make a change in your script, make sure that the comments are still valid.