VBScript Coding Conventions

Coding conventions are suggestions are designed to help us write code using VB Script.

Coding conventions can include the following: 

• Naming conventions for objects, variables, and procedures

• Commenting conventions

• Text formatting and indenting guidelines 

The main reason for using a consistent set of coding conventions is to standardize the structure and coding style of a script or set of scripts so that we and others can easily read and understand the code.

Using good coding conventions results in clear, precise, and readable source code that is consistent with other language conventions and is intuitive.

Variable Naming Conventions

To enhance readability and consistency, we have to use the following prefixes with descriptive names for variables in our VBScript code.

Subtype         Prefix             Example
----------------------------------------------

Boolean         bln                  blnFound

-----------------------------------------------
Byte              byt                  bytRasterData

-----------------------------------------------------
Date (Time)   dtm                 dtmStart

----------------------------------------------------
Double          dbl                  dblTolerance

-----------------------------------------------------
Error             err                   errOrderNum

----------------------------------------------------- 
Integer          int                   IntQuantity

-----------------------------------------------------
Long             lng                   lngDistance

----------------------------------------------------- 
Object           obj                   objCurrent

-----------------------------------------------------
Single           sng                  sngAverage

-----------------------------------------------------

String           str                    strFirstName

-----------------------------------------------------

Object Naming Conventions:

The following table lists recommended conventions for objects you may encounter while programming VBScript.

Object type           Prefix        Example

---------------------------------------------------

3D Panel               pnl            pnlGroup

---------------------------------------------------

Animated button    ani            aniMailBox

---------------------------------------------------

Check box             chk            chkReadOnly

---------------------------------------------------

Combo box            cbo            cboEnglish

---------------------------------------------------

Command button   cmd            cmdExit

---------------------------------------------------

Common dialog     dlg             dlgFileOpen

---------------------------------------------------

Frame                 fra              fraLanguage

---------------------------------------------------

Image                 img            imgIcon

---------------------------------------------------

Label                   lbl             lblHelpMessage

---------------------------------------------------

Line                    lin              linVertical

---------------------------------------------------

List Box               lst             lstPolicyCodes

---------------------------------------------------

Spin                    spn            spnPages

---------------------------------------------------

Text box              txt             txtLastName

---------------------------------------------------

Slider                  sld             sldScale

---------------------------------------------------

Code Commenting Conventions

All procedures should begin with a brief comment describing what they do. This description should not describe the implementation details (how it does it) because these often change over time, resulting in unnecessary comment maintenance work, or worse, erroneous comments. The code itself and any necessary inline comments describe the implementation.

Arguments passed to a procedure should be described when their purpose is not obvious and when the procedure expects the arguments to be in a specific range. Return values for functions and variables that are changed by a procedure, especially through reference arguments, should also be described at the beginning of each procedure.

Procedure header comments should include the following section headings. For examples, see the "Formatting Your Code" section that follows.

Section Heading     Comment Contents

Purpose:   What the procedure does (not how).

Assumptions:   List of any external variable, control, or otherelement             whose state affects this procedure.

Effects:    List of the procedure's effect on each external variable, control, or other element.

Inputs:  Explanation of each argument that is not obvious. Each argument should be on a separate line with inline comments.

Return Values:    Explanation of the value returned.

Remember the following points:

•Every important variable declaration should include an inline comment  describing the use of the variable being declared.

•Variables, controls, and procedures should be named clearly to ensure that inline comments are only needed for complex implementation details.

•At the beginning of your script, you should include an overview that describes the script, enumerating objects, procedures, algorithms, dialog boxes, and other system dependencies. Sometimes a piece of pseudocode describing the algorithm can be helpful.

Formatting the Code

Screen space should be conserved as much as possible, while still allowing code formatting to reflect logic structure and nesting. Here are a few suggestions:

•    Indent standard nested blocks four spaces.

•    Indent the overview comments of a procedure one space.

•    Indent the highest level statements that follow the overview comments four spaces, with each nested block indented an additional four spaces.

The following code adheres to VBScript coding conventions.

'*********************************************************

' Purpose: Locates the first occurrence of a specified user

'          in the UserList array.

' Inputs: strUserList(): the list of users to be searched.

'         strTargetUser: the name of the user to search for.

' Returns: The index of the first occurrence of the strTargetUser

'          in the strUserList array.

'          If the target user is not found, return -1.

'*********************************************************

Function intFindUser (strUserList(), strTargetUser)

    Dim i   ' Loop counter.

    Dim blnFound   ' Target found flag

    intFindUser = -1

    i = 0   ' Initialize loop counter

    Do While i <= Ubound(strUserList) and Not blnFound

      If strUserList(i) = strTargetUser Then

         blnFound = True   ' Set flag to True

         intFindUser = i   ' Set return value to loop count

      End If

      i = i + 1   ' Increment loop counter

    Loop

End Function