Coding Standards for Visual Basic (1/2)

Introduction

The purpose of this document is to provide quality guidelines for the control of code developed in Visual Basic, ensuring some degree of discipline is employed in the development environment. In addition these standards are designed to increase readability, maintainability, reliability and portability of Visual Basic programs.

Contents:

Comments
Sub-Routines and Functions
Forms and Modules
Naming Standards

General Objects
Database Objects
DataTypes, Variables and Functions
Variables
Functions

Global Variables & Constants

Comments

All code should contain a degree of commenting to lend clarity to the processes taking place in the procedures, functions, events etc. This is not only useful for any future development or enhancement that may take place but provides useful reference for the current developer. Comments within the code should be brief and informative, containing as little technical jargon as possible. Some example code is shown below.

'''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
' Check if user has amended a retrieved record to ensure    '
' that amendments are not accidently cancelled              '
'''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
If Me.Caption = FstrFormCaption(RETRIEVE_RECORD) Then
    If blnHaveDepFieldsChanged(Me) Then
        strTitle = "Clear Form"
        strMsg = "Are you sure you want to clear the " _
          & "form and lose any changes made?"
        If Not OkToProceedMsgBox(strTitle, strMsg) Then 
            '''''''''''''''''''
            ' cancel selected '
            ''''''''''''''''''' 
            Exit Sub
        End If
    End If
End If

''''''''''''''''''''''''''''''''''''''''''
' close down current action form if open '
''''''''''''''''''''''''''''''''''''''''''
For I = 0 To Forms.Count - 1
    If Forms(I).Name = "frmCurrActions" Then
        Unload Forms(I)
    End If
Next I

Sub-Routines and Functions
All user defined Procedures and Functions (these are non-object generated sub-routines such as Events) should be prefixed by a comments box providing a brief description of the sub-routine's purpose or function and it's relevant calls. Comment templates for most sub-routines are shown below.

''''''''''''''''''''''''''''''''''''''''''''''''''''
' Object        :
' Description   :
'
' Calls To      :
'
''''''''''''''''''''''''''''''''''''''''''''''''''''

''''''''''''''''''''''''''''''''''''''''''''''''''''
' Procedure     :
' Description   :
' Parameters    :
'
' Called By     :
'
''''''''''''''''''''''''''''''''''''''''''''''''''''

''''''''''''''''''''''''''''''''''''''''''''''''''''
' Function          :
' Description       :
' Parameters        :
'
'
' Called By         :
' Value Returned    :
'
''''''''''''''''''''''''''''''''''''''''''''''''''''

''''''''''''''''''''''''''''''''''''''''''''''''''''
' Property      :
' Description   :
' 
'
''''''''''''''''''''''''''''''''''''''''''''''''''''

Forms and Modules
Each individual Form, Module, Class Module and ActiveX control should also contain a comments box, describing the overall purpose behind the object. This comments box should be positioned at the top of the code, before the 'Option Explicit' Section. Templates are shown below. All sections of this comments box should be completed apart from the Modification History, although a blank modification history should still be provided. If a developer is required to add a fix or modification to another developers code, even prior to release, the modification history must be completed by the developer providing full explanation of the changes made and the reason for the change. All Database tables that are referenced within a form or module should be listed. These should be listed next to the 'Database' heading in the comments box.

''''''''''''''''''''''''''''''''''''''''''''''''''''
'   Module          :
'
'   Description     :
'
'
'
'   Database        :
'
'
'   Author          :   
'
'   Date            :
'
'
'   Modification History:
'
'
'   Author          Date            Reason      Comment
'   ---------       ---------       --------    ---------
'
'
'
'
'''''''''''''''''''''''''''''''''''''''''''''''''''''''''

'''''''''''''''''''''''''''''''''''''''''''''''''''''''''
'   Form            :
'
'   Description     :
'
'
'
'   Database        :
'
'
'   Author          :   
'
'   Date            :
'
'
'   Modification History:
'
'
'   Author          Date            Reason      Comment
'   ---------       ---------       --------    ---------
'
'
'
'
'''''''''''''''''''''''''''''''''''''''''''''''''''''''''

Naming Standards

Objects

All controls added to a Form should be named according to their content or function to allow greater understanding of their function. Avoid leaving any controls with their default names. E.g.,

where Text1 is the default name for a TextBox displaying a Forecast total, it could be renamed…

    txtForecastTotal

where more than one total is displayed or

    txtTotal

where it is the only total on the form.

All control names should be prefixed with an appropriate three letter acronym (in lower case) describing the controls type. Below is a list of examples.

TextBox txt

Label lbl

Frame fra

Command Button cmd

CheckBox chk

DropDownCombo cbo

ListBox lst

Grid grd

Databound Grid dbg

FlexGrid fxg

RadioButtons opt

Timer tmr

TreeView tvw

ListView lvw

ImageList img

Menu Item mnu

User Control ctl

Form frm

Module mod

Class Module cls

Database Objects

All database objects should be named according to similar standards.

Database db

Recordset rs

TableDef tdf

Table tbl

Field fld

QueryDef qdf

Workspace ws

DataTypes, Variables and Functions

DataTypes should also be prefixed to allow for greater understanding of the code.

Byte byt

Boolean bln

Integer int

Long lng

Single sng

Double dbl

Currency cur

Decimal dec

Date dte

Object obj

String str

Variant var

These rules also apply to the declaration of function names, where the returned value should be reflected in the Function name.Examples:

Variables

Dim intCounter as integer

Dim blnFlag as Boolean

Functions

Function blnCompareTotals(intForecastTotal as Integer) as Boolean

Global Variables & Constants

Globals

For shared Projects (VBPs) Global variables should be defined in a common module (modGlobals), otherwise Globals should declared in one place in the project being developed. This is to ensure a central reference is available and avoid any naming conflicts.
In order to identify globals within code prefix them with 'g'. Therefore, intCounter would become gintCounter.
When creating a new Global variable ensure a brief description of the variable is provided for reference by other developers. Example:

'Indicates if user has authority
Global gblnAuthorityFlag as Boolean

Constants

Constants should be entered in Capitals.

Example

Const HIGHLIGHT = &H8000000D&

All public constants should be declared within the globals module (modGlobals) in the Constants section provided. As with the global variables, a brief description should be provided, either for groups of constants or individual ones.

Continue with VB Coding Standards (2/2)