1q;xVisual Basic Programming Conventions from Microsoft Consulting Services

1. Naming Conventions

1.1 Objectives

nTo help programmers (especially in multiprogrammer projects) standardize and decode the structure and logic of an application
nTo be precise, complete, readable, memorable, and unambiguous
nTo be consistent with other language conventions (most importantly the Visual Basic Programmer's Guide and standard Microsoft Windows Hungarian C)
nTo be efficient from a string size and labor standpoint, thus allowing a greater opportunity for longer/fuller object names

nTo define the minimum requirements necessary to do the above





Note:

On pages 32 and 33 of the Visual Basic 2 Programmer's Guide, Visual Basic has defined control naming conventions that will likely be adopted by many corporations and Visual Basic ISVs. As a result, it would take a very strong argument to justify deviating from the Visual Basic 2 standard without causing a lot of heartache and confusion. Lacking such a compelling argument, this document therefore is a superset of the published Visual Basic conventions.



1.2 Conventions
1.2.1 Option Explicit

"Option Explicit" must always be used to force proper variable declarations and aid good variable commenting. The time lost trying to track down bugs caused by typos (aUserNameTmp vs. sUserNameTmp vs. sUserNameTemp) far outweighs the time needed to Dim variables.

1.2.2 Control naming

The following table defines our standard Control name prefixes. (These are consistent with those documented in the Visual Basic 2 Programmers Guide.)

Table 1. Standard Control Name Prefixes

PrefixControl Type Description


aniAnimation button
bedPen Bedit
cboCombobox and dropdown Listbox
chkCheckbox
clpPicture Clip
cmdCommand Button
comCommunications
ctrControl (Used within procs when the specific type is unknown)
dbODBC Database
dirDir List Box
dlgVisual Basic Pro Common Dialog
drvDrive List Box
dsODBC Dynaset
filFile List Box
frmForm
fraFrame
gauGauge
gpbGroup Push Button
grdGrid
hedPen Hedit
hsbHorizontal Scroll Bar
imgImage
inkPen Ink
keyKeyboard key status
lblLabel
linLine
lstListbox
mpmMAPI Message
mpsMAPI Session
mciMCI
mnuMenu
optOption Button
oleOle Client
picPicture
pnl3d Panel
shpShape
spnSpin Control
txtText/Edit Box
tmrTimer
vsbVertical Scroll Bar
1.3 Control Prefix Notes
1.3.1 Menus

Because Menu handlers can be so numerous, Menu names require a little more attention. Menu prefixes therefore continue beyond the initial Mnu label by adding an additional (upper case) character prefix for each level of nesting, with the final menu caption being spelled out at the end of the name string. When there is ambiguity caused by character duplications, such as a menu having both main Format and File menus, use an additional (lower case) character to differentiate the items. Examples:

Menu Caption SequenceMenu Handler Name


Help.ContentsmnuHContents
File.OpenmnuFiOpen
Format.CharactermnuFoCharacter
File.Send.Fax mnuFSFax
File.Send.EmailmnuFSEmail
This results in all the family members of a particular menu group being listed right next to each other. This multi-tiered format provides a very direct way to find a menu handler, especially when there are a great many of them.

1.3.2 Other controls

For new controls not listed above, try to come up with a unique 3-character prefix. However, it is more important to be clear than to stick to 3 characters. For derivative controls, such as an enhanced list box, extend the prefixes above so that there is no confusion about what control is really being used. For example, a control instance created from the Visual Basic Pro 1.0 3D Frame could use a prefix of fra3d to make sure there is no confusion over which control is really being used.

1.3.3 Variable and routine naming

Variable and function names have the following structure:





The prefix describes the use and the scope of the variable, as in iGetRecordNext and sGetNameFirst. The qualifier is used to denote standard derivatives of a base variable or function, as in iGetRecordNext and sGetNameFirst. The suffix is the optional Visual Basic type char ($, %, #, and so on).

Prefixes

The following table defines variable/function name prefixes that are based on Hungarian C. These must be used universally, even when Visual Basic suffixes (such as %, &, #, and so on) are also used.

Table 2. Prefixes for Variable and Function Names

PrefixVariable Use Description (precedes Control prefix and body)


bBoolean (vb type = %)
cCurrency - 64 bits (vb type = @)
dDouble - 64 bit signed quantity (vb type = #)
dbDatabase
dsDynaset
dtDate+Time (vb type = variant)
fFloat/Single - 32 bit signed floating point (vb type = !)
hHandle (vb type = %)
iIndex (vb type = %)
lLong - 32 bit signed quantity (vb type = &)
nInteger (sizeless, counter) (vb type = %)
sString (vb type = $)
uUnsigned - 16 bit unsigned quantity (must use &)
ulUnsigned Long - 32 bit unsigned quantity (must use #)
vntVariant (big and ugly to discourage use and make sure it gets the reader's attention)
wWord - 16 bit signed quantity (vb type = %)
aArray
User defined type
PrefixScope or Use (precedes Use prefix above)


gGlobal
mLocal to module or form
stStatic variable
vVariable passed by value (local to a routine)
rVariable passed by reference (local to a routine)
Hungarian is as valuable in Visual Basic as it is in C because the Visual Basic type suffixes alone do not provide standard (and valuable) information about what a variable/function is used for or where it is accessible. For example, iSend (which might be a count of the number of messages sent), bSend (which might be a flag/Boolean defining the success of the last Send operation), and hSend (which might be a handle to the Comm interface) all succinctly tell a programmer something very different. This information is fundamentally lost when the name is reduced down to Send%. Scope prefixes such as g and m also help reduce the problem of name contention, especially in multideveloper projects. Hungarian is also well known to Windows programmers and constantly referenced in Microsoft and industry programming books. Additionally, the bond between C programmers and Visual Basic programmers can be expected to become much stronger as Visual C++ begins to live up to its potential. This transition will result in many Visual Basic programmers moving to C for the first time and many programmers moving fluidly back and forth between each environment.

Body

The body of variable and routine names should use mixed case and should be as long as needed to describe their purpose. Function names should also begin with a verb, such as InitNameArray or CloseDialog.
For frequently used or long terms, abbreviations (such as Init, Num, Tbl, Cnt, and Grp for Initialization, Number, Table, Count, and Group) are suggested to help keep name lengths reasonable. Names greater than 32 characters generally begin to inhibit readability on VGA displays. When abbreviations are used, they must be used consistently throughout the application. Randomly switching between "Cnt" and "Count" within a project will greatly frustrate developers.

Qualifiers

Often related variables and routines are used to manage and manipulate a common object. In these cases it can be very helpful to use standard qualifiers to label the derivative variables and routines. Although putting the qualifier after the body of the name might seem a little awkward (as in sGetNameFirst, sGetNameLast instead of sGetFirstName, and so on), this practice will help order these names together in the Visual Basic editor routine lists, making the logic and structure of the application easier to understand.

The following table defines common qualifiers and their standard meaning.

Table 3. Common Qualifiers

QualifierDescription (follows Body)


FirstFirst element of a set.
LastLast element of a set.
NextNext element in a set.
PrevPrevious element in a set.
CurCurrent element in a set.
MinMinimum value in a set.
MaxMaximum value in a set.
SaveUsed to preserve another variable which must be reset later.
TmpA "scratch" variable whose scope is highly localized within the code. The value of a Tmp variable is usually only valid across a set of contiguous statements.
SrcSource. Frequently used in comparison and transfer routines.
DstDestination. Often used in conjunction with Source.
1.3.4 Constant naming

nThe body of constant names are described in UPPER_CASE with underscores ("_") between words.
nAlthough standard Visual Basic constants do not include Hungarian use information, prefixes such as i, s, g, and m can be very useful in understanding the value and scope of a constant, so constant names follow the same rules as variables. Examples:




mnUSER_LIST_MAX'Max entry limit for User list (integer value, local to module)
gsNEW_LINE'New Line character string (global to entire application)
1.3.5 Variant data types

With the single exception listed below, variants should NOT be used. When a type conversion is needed, variant use would probably provide a slight performance win over the explicit basic type conversion routines (val(), str$(), and the like), but this gain is not sufficient to overcome the ambiguity and general sloppiness they allow in code statements.
Example:



vnt1 = "10.01" : vnt2 = 11 : vnt3 = "11" : vnt4 = "x4"
vntResult = vnt1 + vnt2 ' Does vntResult = 21.01 or 10.0111?
vntResult = vnt2 + vnt1 ' Does vntResult = 21.01 or 1110.01?
vntResult = vnt1 + vnt3 ' Does vntResult = 21.01 or 10.0111?
vntResult = vnt3 + vnt1 ' Does vntResult = 21.01 or 1110.01?
vntResult = vnt2 + vnt4 ' Does vntResult = 11x4 or ERROR?
vntResult = vnt3 + vnt4 ' Does vntResult = 11x4 or ERROR?

Additionally, the type conversion routines assist in documenting implementation details, which make reading, debugging, and maintaining code more straightforward.
Example:



(iVar1 = 5 + val(sVar2) 'use this
vntVar1 = 5 + vntVar2 'not this!

Exception

While working with databases, messages, DDE, or OLE, a generic service routine can receive data that it does not need to know the type of in order to process or pass on.
Example:



Sub ConvertNulls(rvntOrg As Variant, rvntSub As Variant)
'If rvntOrg = Null, replace the Null with rvntSub
If IsNull(rvntOrg) Then rvntOrg = rvntSub
End Sub

2. Commenting

nAll procedures and functions must begin with a brief comment describing the functional characteristics of the routine (what it does). 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 or local comments will describe the implementation. Parameters passed to a routine should be described (a) if they are not obvious and (b) when specific ranges are assumed by the routine. Function return values and global variables that are changed by the routine (especially through reference parameters) must also be described at the beginning of each routine.

nEvery nontrivial variable declaration should include an inline comment describing the use of the variable being declared.
nVariables, controls, and routines should be named clearly enough that inline commenting is only needed for complex or nonobvious implementation details.
nAn overview description of the application enumerating primary data objects, routines, algorithms, user interface dialogs, database and file system dependencies, and so on, should be included at the start of the .BAS module that contains the project's Visual Basic generic constant declarations.

Note The Project window inherently describes the list of files in a project, so this overview section only needs to provide information on the most important files and modules or files that the Project window doesn't know about, such as .INI or database files.

3. Code Formatting

Because many programmers still use VGA displays, screen real estate must be conserved as much as possible while still allowing code formatting to reflect logic structure and nesting. For this reason:

nStandard (tab-based) block nesting indentations should be from two to four spaces. More than four spaces is unnecessary and causes unnecessary statement hiding through truncation. Fewer than two is not effective in reflecting logic nesting.
nThe functional overview comment of a routine should be indented one space. The highest level statements that follow the overview comment should be indented one tab, with each nested block indented an additional tab. Example:



Function iFindUser (rasUserList() as String, rsTargetUser as String) as Integer
'Search UserList and if found, return index of first occurrence of TargetUser,
' else return -1
Dim i as Integer 'loop counter
Dim bFound as Integer 'target found flag
iFindUser = -1
i = 0
While i <= Ubound(rasUserList) and Not bFound
If rasUserList(i) = rsTargetUser Then
bFound = True
iFindUser = i
End If

Wend
End Function

nVariables and nongeneric constants should be grouped by function rather than being split off into isolated areas or special files. (Visual Basic generic constants such as "HOURGLASS" should be grouped in a generic section of a main global file so that they do not complicate the reading of the application-specific declarations.)

4. Operators

nAlways use "&" when concatenating strings and "+" when working with numerical values. Using only "+" can cause problems when operating on two variants. For example:



vntVar1 = "10.01"
vntVar2 = 11
vntResult = vntVar1 + vntVar2 'vntResult = 21.01
vntResult = vntVar1 & vntVar2 'vntResult = 10.0111


5. Scope

nAlways define variables with the smallest scope possible. Global variables can create enormously complex state machines and make understanding the logic of an application extremely difficult. They also make the reuse and maintenance of your code much more difficult. If you have to use globals, keep their declarations grouped by functionality and comment them well.
nWith the exception of globals that should not be passed, procedures and functions should only operate on objects that are passed to them. Global variables that are used in routines should be identified in the general comment area at the beginning of the routine.

nLikewise, try to put as much logic and as many user interface objects in Dialog Boxes as possible. This will help segment your application's complexity and minimize its run-time overhead.








MS Developer Network CDe routine. Funcq;w?/[ ?? @[ `[EE0\[\\\[??\'5\/'5`??,wQ#%$$')?A&(*@@Ps#G[l&0=Oajt


-
/
."$MOQm



')+-PRQ|~RT@MY{D\%T]qEDCBAsu$ & ( G d >!!!$"]"t"v""#####,$r$$$%%%%&&&:&|&&'B''''f(p(r(t(v(((((())))))))+*4*6*E*G*F+E,,-.--G.F/r/t/s0s00000`1b1V2:3<3>3@3333,4h4|4444455*5,565D5F5E66666M7O7Q7S7f7t777788
899~:::J;L;N;P;R;T;V;X;Z;q;s;7 Arialile i <= Ubound(rasUserList) and Not bFound
If rasUserList(i) = rsTargetUser Then
bFound = True