• D
  • Coding and Naming Conventions for VBScript Developers
    • Using Variable Naming Conventions
    • Providing Cues about Variable Scope
    • Using Descriptive Variable and Procedure Naming
    • Using Object Naming Conventions
    • Using Constant Naming Conventions
    • Commenting Your Code
    • Using VBScript in HTML Documents
    • Listing D.1. Using VBScript in HTML documents.

-D-

Coding and Naming Conventions
for VBScript Developers

This appendix outlines a variety of recommended coding and variable naming conventions for VBScript developers. Coding and naming conventions are suggestions or recommendations to standardize the way in which developers implement the most basic of functionality in a language or development environment. Naming and coding conventions can cover topics such as these:

• Variable naming

• Variable scope prefixes

• Procedure naming

• Object naming

• Constant naming

• Code commenting

• Using VBScript in HTML documents

You might wonder why you should bother with using conventions. The main reason is that, by following a standardized set of recommendations, you are making your code easier to read, understand, and maintain--for others as well as yourself. Using standard conventions helps ensure that you are speaking the same "dialect" of the VBScript language as most of your fellow Visual Basic developers.

Using Variable Naming Conventions

Although VBScript has just one primary data type (the Variant type), it has several subtypes. As you might expect, using a standard naming convention for each subtype helps you and fellow developers immediately recognize the subtype of a variable simply by reading its name. VBScript variable naming conventions use standard prefixes. Table D.1 lists the recommended prefixes and an example of each.

Table D.1. VBScript Variable Naming Conventions.

Subtype	Prefix	Example
Boolean	bln	blnFound
Byte	byt	bytPixelData
Date (Time)	dtm	dtmBegin
Double	dbl	dblDelta
Error	err	errOrderNum
Integer	int	intTotal
Long	lng	lngDist
Object	obj	objCurrent
Single	sng	sngAverage
String	str	strLastName

Microsoft recommends that you use the prefixes listed in this table along with descriptive names when naming variables in your scripts.

Complex VBScripts can grow in size rapidly. When this is the case, it is nice to be able to determine something about the scope of variables in use. VBScript variable scopes occur on two levels:

• Procedure-level scoping applies to variables declared in events, functions, or subprocedures. The visibility of these variables is limited to the procedure in which they are declared.

• Script-level scoping applies to variables declared in the HEAD section of an HTML document (in other words, outside of any procedure). These variables are visible to all procedures in the script.

To provide a simple indication of a variable's scope (without increasing its size too much), Microsoft recommends that you add a single-letter prefix to the names of script-level variables. A procedure-level variable of subtype Double, for example, might be named dblAmplitude (note that no prefix is used). A script-level variable, however, would be prefixed with the letter s. A variable of Boolean subtype might be named sblnErrorOccurred. Naming the variable in this manner gives an instant indication to anyone reading the code that this is a Boolean type with script-level scope.

A few guidelines for naming variables and procedures in your scripts follow:

• A variable name should be of mixed case and long enough to indicate its meaning. Additionally, a variable name should conform to the naming conventions outlined in Table D.1.

• A procedure name should begin with a verb, should consist of mixed case, and should be long enough to indicate its meaning. A procedure that initializes an array of employee names, for example, might be named InitEmployeeNameArray.

• To maintain the readability of your scripts, you should limit your variable names to 32 characters.

• If you use longer terms frequently, you can use standard abbreviations. Make sure that you use abbreviations (such as Cnt for Count) consistently to avoid confusion in your scripts.

Using a standard naming convention for various objects referenced in your scripts helps you and fellow developers immediately recognize the object type simply by reading its name. Just as with variable naming, VBScript object naming conventions use standard prefixes. Table D.2 lists the recommended prefixes and an example of each.

Table D.2. VBScript Object Naming Conventions.

Object Type	Prefix	Example
3D panel	pnl	pnlGroup
Animated button	ani	aniUserMailBox
Checkbox	chk	chkReadWrite
Combo box,	cbo	cboEnglish
drop-down listbox
Command button	cmd	cmdExit
Common dialog box	dlg	dlgFileOpen
Frame	fra	fraLanguage
Horizontal scrollbar	hsb	hsbSoundLevel
Image	img	imgFTPIcon
Label	lbl	lblWarningMessage
Line	lin	linHorizontal
Listbox	lst	lstProductIDs
Slider	sld	sldPercentage
Spin	spn	spnPages
Textbox	txt	txtFirstName
Vertical scrollbar	vsb	vsbRate

Microsoft recommends that you use the prefixes listed in this table along with descriptive names when naming objects in your scripts.

To easily differentiate constants from variables in your scripts, Microsoft recommends that you make constant names all uppercase and that you use the underscore (_) character between words if the name consists of more than one word. You might use MAX_LIST_INDEX, for example, to specify a constant that has the value of the highest index in an array used in the script.

Anyone who has had the responsibility of maintaining code developed by someone else will attest to the fact that poorly documented and commented code often just exacerbates an already difficult situation. Instead of focusing on fixing bugs or enhancing functionality, code maintainers often are disproportionately concerned with just figuring out what the existing code is supposed to be doing. Therefore, I highly recommend that you get in the habit of commenting your code consistently and accurately.

A few guidelines for commenting your scripts follow:

• Your scripts should include a header section that describes what the script does--not the details of how it does it (these details are subject to change over time). The header section also should briefly describe objects, procedures, algorithms, dialog boxes, and other system dependencies. Table D.3 summarizes Microsoft's recommendations for the contents of the header section.

• Include pseudocode (or structured English) in the header section when doing so helps to describe algorithms being implemented.

• Important variable declarations should include inline comments describing the use of the variable.

• You should name variables, controls, and procedures using descriptive names that follow the guidelines presented in this appendix. Use inline comments to elaborate on more complex details when appropriate.

• You should briefly describe any arguments that are passed to a procedure--especially if their purpose is not immediately obvious or if the procedure expects the value of the arguments to be within a specific range.

• You should describe any function return values and other variables changed by the procedure (especially through reference arguments) at the beginning of each procedure.

Table D.3. Recommended Contents for Script HeaderSections.

Header Section	Description of Contents
Purpose	Describes what the procedure does--not a detailed account of how
Assumptions	Lists any external variables, controls, or other elements whose state affects this procedure
Effects	Describes the effect the procedure has on each external variable, control, or other element
Inputs	Explains arguments that are not obvious; each argument should be on a separate line with inline comments
Return Values	Explains the value returned

Here are a few guidelines that Microsoft recommends for using VBScript in your HTML documents:

• VBScript procedures, including event procedures for controls, generally should be included in the <HEAD> section of the document. This improves readability by keeping all the code in one place. Many developers prefer to include VBScript code at the end of the HTML document instead. This also is fine; just try to be consistent and keep all code in the same place in the document.

• Use HTML comment tags (<! and >) to bracket any scripting code to ensure that this code will be hidden from browsers that don't support the <SCRIPT> tag.

Listing D.1 shows a template that demonstrates these guidelines for using VBScript in HTML documents.

Listing D.1. Using VBScript in HTML documents.

<! Template for VBScript enabled pages >
<HTML>
<HEAD>
<TITLE> </TITLE>
<SCRIPT LANGUAGE="VBScript">
<!
        Function WeCanDeliver (Dt)
                WeCanDeliver = (Cdate(Dt) - Now()) > 2
        End Function
>
</SCRIPT>
</HEAD>
<BODY>
<FONT FACE=ARIAL SIZE=2> <! global default >

... your HTML content goes here ...

</FONT>
</BODY>
</HTML>