Creating Scripts That Are Easier to Read

Microsoft® Windows® 2000 Scripting Guide

« Previous | Next »   

Most people think of scripts as something that you run, not something that you read. However, scripts are actually read far more than you might think. Obviously the original author of the script needs to read the code from time to time; however, so do others charged with maintaining and modifying the code, people hoping to learn something about scripting from reading the code, and system administrators who want to know more about the script before they begin using it.

A readable script, using consistent, predictable, and complete code, is easier to maintain and adapt to other uses. Readability might not be important for scripts that are designed to be run once and then discarded. However, if you expect a script to be used repeatedly, and if you expect that other administrators might need to modify your script, readability becomes a concern.

To make your scripts easier to read and understand:

• Use the proper case for VBScript keywords.
• Phrase If Then statements positively.
• Order If Then and Select Case statements logically.
• Use Boolean expressions rather than literal values in conditional statements.
• Use parentheses in mathematical expressions.
• Specify default properties.

Using the Proper Case

VBScript is a case-insensitive language; this means that you can type keywords and statements in uppercase, lowercase, or any combination without generating a syntax error. For example, the four case styles shown in the following are all syntactically equivalent:

wsCRIpt.EchO "This is a valid VBScript statement." wSCRIPt.eCHo "This is a valid VBScript statement." WSCRIPT.ECHO "This is a valid VBScript statement." Wscript.Echo "This is a valid VBScript statement." 

Although the four styles are syntactically equivalent, some are definitely easier to read than others, and the combination of the four different styles results in a document that is difficult to read. To enhance readability, type VBScript keywords, statements, and other elements using Pascal casing. To use Pascal casing, begin each individual word with an uppercase letter, and type remaining letters in lowercase. This is not only easier to read but also helps distinguish the VBScript elements from the rest of the text.

In the following script snippet, Pascal casing is used to distinguish keywords from variables and constants:

Const MANAGER_JOB_TITLE_ID = 100 Select Case Case strDepartment = "Accounting"     If intJobTitle = MANAGER_JOB_TITLE_ID Then         intRatingScale = 1     Else         intRatingScale = 2     End If Case strDepartment = "Administration"     intRatingScale = 1 Case Else     intRatingScale = 2 End Select 

Phrasing If Then Statements

Compared with programming languages such as C and C++, the syntax of scripting languages is almost conversational. Scripting languages allow you to write your script in a fashion somewhat similar to ordinary speech. You should take advantage of this when writing scripts and try to mimic typical conversational patterns and syntax whenever possible. This makes your scripts easier to read and understand because the code appears more like ordinary language than computer programming.

Note

• Brian Kernighan, author of a number of books on programming style and programming conventions, refers to this as the "telephone test." He believes you should attempt to read your code to someone over the telephone. If the person on the other end does not understand what you are talking about, then you need to rewrite your code.

For example, consider the phrasing of If Then statements in your scripts. In conversation, people generally phrase these statements positively. Suppose that stores in the state of Washington charge a special sales tax to residents of the state but not to residents of other states. If you are a store owner in Washington, you would likely to explain your store s sales tax policy by saying, "If the customer is from Washington state, then we charge them sales tax. Otherwise, we do not."

Your If Then statements should use a similar syntax. For example, the following script uses valid VBScript syntax but is awkward to read (try reading it out loud):

If (Not State = "WA") Then     SngSalesTax = 0 End If 

A grammatical construction such as If Not State Equals Washington causes confusion. Instead of testing for the negative condition, test for the positive condition, as shown in the following snippet. Read this script aloud, and notice that it sounds less awkward.

If (State = "WA") Then     SngSalesTax = .065 End If 

Or you might use the does not equal (<>) operator:

If (State <> "WA") Then     SngSalesTax = 0 End If 

Using Boolean Expressions in Conditional Statements

When checking the value of a Boolean (True/False) expression, script writers often use a syntax such as this:

If blnIsUSCitizen = True Then     Wscript.Echo "This person is a citizen." Else     Wscript.Echo "This person is not a citizen." End If 

On the surface, this statement appears to pose no problems. In reality, however, a statement like this can return the value False even when the expression is actually True. This is because VBScript sets the value of True to 1, while most programming languages set the value of True to 1. As a result, the following situation can occur:

• Someone saves the value 1 (True) to a database using a Visual Basic program.
• Someone else uses VBScript to check the value. The statement If blnIsUSCitizen = True can be translated to read, "If blnUSCitizen equals 1" with 1 representing the value of True in VBScript.
• Because the value in this case is actually 1 rather than 1, the script decides that blnIsUSCitizen is False, even though it is actually True.

To avoid this problem, use syntax similar to that shown in the following script snippet. In this case, the statement "If blnIsUSCitizen Then" is used as the condition. This statement translates as, "If blnIsUSCitizen equals anything other than 0." Because 1 is not 0, the condition is correctly interpreted as being True.

If blnIsUSCitizen Then     Wscript.Echo "This person is a citizen." Else     Wscript.Echo "This person is not a citizen." End If 

By contrast, False is always assigned 0. When you check for a False value, you can look for either False or for 0. For the sake of consistency, however, it is generally best to test for False as shown in the following snippet:

If blnIsUSCitizen = False Then     Wscript.Echo "This person is not a citizen." Else     Wscript.Echo "This person is a citizen." End If 

Using Parentheses in Mathematical Expressions

Parentheses serve two purposes in mathematical equations: they force the order of arithmetic precedence, and they enhance readability. These two functions are illustrated in the following script snippet. This script works as expected: It multiplies the regular price of an item by the tax rate, multiplies the standard discount rate by a preferred customer rate, and then subtracts the total discount from the total regular price. However, the equation is somewhat difficult to read, and the fact that it works is, in part, an accident: The different terms and operators used in the equation just happen to be arranged in a way that respects the order of precedence.

RegPrice = 100 Discount = 5 SalesTax = 1.05 PreferredCustomer = 2 Wscript.Echo RegPrice * SalesTax - Discount * PreferredCustomer 

Although the equation works as expected, someone editing the script might have difficulty understanding how the calculation works. If so, he or she might try to group the items within parentheses. If those parentheses are misplaced, the equation yields unexpected results. For example, one placement produces a correct answer, but another placement produces an incorrect answer:

• Correct: (100 * 1.05) (5 * 2) = 95
• Incorrect: 100 * (1.05 5) * 2 = 790

To avoid problems such as this, always use parentheses when performing calculations that have the following characteristics:

• Have three or more elements
• Use more than one type of operator (for example, an equation that includes both addition and division)

A revised version of the script, which groups the items into logical sets, is shown in the following snippet:

RegPrice = 100 Discount = 5 SalesTax = 1.05 PreferredCustomer = 2 Wscript.Echo (RegPrice * SalesTax) - (Discount * PreferredCustomer) 

Specifying Default Properties in Statements

Automation objects often have default properties associated with them. A default is simply the property that is used unless a different property is specified. For example, in WSH the Arguments object has the default property Item. In VBScript, you can omit the property name when working with the default property of an item. Thus, you can write the following script to cycle through the arguments passed to that script:

Set objArgs = WScript.Arguments For i = 0 to objArgs.Count - 1      WScript.Echo objArgs(i) Next 

Although VBScript allows you to omit default properties, it is a good idea to always include the default property name as part of your script. This makes your code easier to read and understand, especially if you are working with an automation object whose default property is not widely known. To ensure that there is no doubt as to which property is being employed, you should use code similar to this, which clearly specifies the default property Item:

Set objArgs = WScript.Arguments For i = 0 to objArgs.Count - 1    WScript.Echo objArgs.Item(i) Next 

Note

• Preparing for Visual Basic .NET. Default properties are not supported in Visual Basic .NET. In Visual Basic .NET, you must always specify the property name.

---

 Send us your feedback

« Previous | Next »