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.

:  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
End Function


Post a Comment