Web Database Developer's Guide with Visual Basic 5

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

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.

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.

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>