RVBA Naming Conventions

Version 6.04

Copyright © 1992-2005 by Gregory Reddick

Index:
Introduction
Changes to the Conventions
An Introduction to Hungarian
Tags
  Variable tags
  Constructing Properties Names
  Collection Tags
  Constants
  Menu Items
Creating Data Types
  Enumerated types
  Tags for classes and user-defined types
  Polymorphism
Constructing Procedures
  Constructing Procedure Names
  Naming Parameters
  Naming Labels
Prefixes
  Arrays of Objects Prefix
  Index Prefix
  Prefixes for Scope and Lifetime
  Other Prefixes
Suffixes
File Names
Host Application and Component Extensions Tags
  Access Objects
  DAO Objects
  Visual Basic Objects
  ActiveX Data Objects
  ADO Ext. for DDL and Security (ADOX)
  Jet and Replication Objects
  Common Control Objects
  Other Custom Controls and Objects
Summary

Introduction

The purpose of the Reddick VBA (RVBA) Naming Conventions is to provide a guideline for naming objects in the Visual Basic for Applications (VBA) language. Having conventions is valuable in any programming project. When you use them, the name of the object conveys information about the meaning of the object. These conventions attempt to provide a way of standardizing that meaning across the body of VBA programmers.

VBA is implemented to interact with a host application—for example, Microsoft Access, Microsoft Visual Basic, AutoCAD, and Visio. The RVBA conventions cover all implementations of the VBA language, regardless of the host application. Some of the tags described in this document may not necessarily have an implementation within some of the particular host programs for VBA. The word object, in the context of this document, refers to simple variables and VBA objects, as well as to objects made available by the VBA host program.

While I am the editor of these conventions, they are the work of many people, including Charles Simonyi, who invented the Hungarian conventions on which these are based, and Stan Leszynski, who co-authored several versions of the conventions. Many others, too numerous to mention, have also contributed to the development and distribution of these conventions, but I'd especially like to thank Paul Litwin and Ken Getz who have made substantial contributions over the years.

These conventions are intended as a guideline. If you disagree with a particular part of the conventions, simply replace that part with what you think works better. However, keep in mind that future generations of programmers may need to understand those changes, and place a comment in the header of a module indicating what changes have been made. To be concise, the conventions are presented without rationalizations for how they were derived although each of the ideas presented has a considerable history to it.

Changes to the Conventions

Some of the tags in the version of the conventions presented here have changed from previous versions. Consider all previous tags to be grandfathered into the conventions—you don't need to go back and make changes. For new development work, I leave it up to you to decide whether to use the older tags or the ones suggested here. In a few places in this document, older tags are shown in {braces}. As updates to this document are made, the current version can be found at http://www.xoc.net.

An Introduction to Hungarian

The RVBA conventions are based on the Hungarian conventions for constructing object names, named for the native country of the inventor, Charles Simonyi. The objective of Hungarian is to convey information about the object concisely and efficiently. Hungarian takes some getting used to, but once adopted, it quickly becomes second nature. The format of a Hungarian object name is

[prefixes]tag[BaseName[Suffixes]]

The square brackets indicate optional parts of the object name. These components have the following meanings:

Notice that the only required part of the object name is the tag. This may seem counterintuitive; you may feel that the BaseName is the most important part of the object name. However, consider a generic procedure that operates on any form. The fact that the routine operates on a form is the important thing, not what that form represents. Because the routine may operate on forms of many different types, you do not necessarily need a BaseName. However, if you have more than one object of a type referenced in the routine, you must have a BaseName on all but one of the object names to differentiate them. In addition, unless the routine is generic, the BaseName conveys information about the variable. In most cases a variable should include a BaseName.

Tags

Use the techniques described in the following sections to construct tags to indicate the data type of an object.

Variable tags

Use the tags listed in Table 1 for VBA data types. You can also use a specific tag instead of obj for any data type defined by the host application or one of its objects. (See the section "Host Application and Component Extensions to the Conventions" later in this document.)

Table 1: Tags for VBA Variables

Here are several examples:

lngCount
intValue
strInput

You should explicitly declare all variables, each on a line by itself. Do not use the old type declaration characters, such as %, &, and $. They are extraneous if you use the naming conventions, and there is no character for some of the data types, such as Boolean. You should always explicitly declare all variables of type Variant using the As Variant clause, even though it is the default in VBA. For example:

Dim intTotal As Integer
Dim varField As Variant
Dim strName As String

Constructing Properties Names

Properties of a class present a particular problem: should they include the naming convention to indicate the type? To be consistent with the rest of these naming conventions, they should. However, it is permitted to have property names without the tags, especially if the class is to be made available to customers who may not be familiar with these naming conventions.

Collection Tags

You treat a collection object with a special tag. You construct the tag using the data type of the collection followed by the letter s. For example, if you had a collection of Longs, the tag is lngs. If it was a collection of forms, the tag for the collection is frms. Although, in theory, a collection can hold objects of different data types, in practice, each of the data types in the collection is the same. If you do want to use different data types in a collection, use the tag objs. For example:

intsEntries
frmsCustomerData
objsMisc

Constants

Constants always have a data type in VBA. Because VBA will choose this data type for you if you don't specify it, you should always specify the data type for a constant. Constants declared in the General Declarations section of a module should always have a scope keyword of Private or Public, and be prefixed by the scope prefixes m or g, respectively. A constant is indicated by appending the letter c to the end of the data type for the constant. For example:

Const intcGray As Integer = 3
Private Const mdblcPi As Double = 3.14159265358979

Although this technique is the recommended method of naming constants, if you are more concerned about specifying that you are dealing with constants rather than their data type, you can alternatively use the generic tag con instead. For example:

Const conPi As Double = 3.14159265358979

Menu Items

The names of menu items should reflect their position in the menu hierarchy. All menu items should use the tag mnu, but the BaseName should indicate where in the hierarchy the menu item falls. Use Sep in the BaseName to indicate a menu separator bar, followed by an ordinal. For example:

mnuFile (on menu bar)
mnuFileNew (on File popup menu)
mnuFileNewForm (on File New flyout menu)
mnuFileNewReport (on File New flyout menu)
mnuFileSep1 (first separator bar on file popup menu)
mnuFileSaveAs (on File popup menu)
mnuFileSep2 (second separator bar on file popup menu)
mnuFileExit (on File popup menu)
mnuEdit (on menu bar)

Creating Data Types

VBA gives you three ways to create new data types: enumerated types, classes, and user-defined types. In each case, you will need to invent a new tag that represents the data type that you create.

Enumerated types

Groups of constants of the long data type should be made an enumerated type. Invent a tag for the type, append a "c", then define the enumerated constants using that tag. Because the name used in the Enum line is seen in the object browser, you can add a BaseName to the tag to spell out the abbreviation indicated by the tag. For example:

Public Enum ervcErrorValue
    ervcInvalidType = 205
    ervcValueOutOfBounds
End Enum

The BaseName should be singular, so that the enumerated type should be ervcErrorValue, not ervcErrorValues. The tag that you invent for enumerated types can then be used for variables that can contain values of that type. For example:

Dim erv As ervcErrorValue
Private Sub Example(ByVal ervCur As ervcErrorValue)

While VBA only provides enumerated types of groups of the long type, you can still create groups of constants of other types. Just create a set of constant definitions using an invented tag. For example:

Public Const estcError205 As String = "Invalid type"
Public Const estcError206 As String = "Value out of bounds"

Unfortunately, because this technique doesn't actually create a new type, you don't get the benefit of the VBA compiler performing type checking for you. You create variables that will hold constants using a similar syntax to variables meant to hold instances of enumerated types. For example:

Dim estError As String

Tags for classes and user-defined types

A class defines a user-defined object. Because these invent a new data type, you will need to invent a new tag for the object. You can add a BaseName to the tag to spell out the abbreviation indicated by the tag. User-defined types are considered a simple class with only properties, but in all other ways are used the same as class modules. For example:

gphGlyph
edtEdit
Public Type grbGrabber

You then define variables to refer to instances of the class using the same tag: For example:

Dim gphNext As New gphGlyph
Dim edtCurrent as edtEdit
Dim grbHandle as grbGrabber

Polymorphism

In VBA, you use the Implements statement to derive classes from a base class. The tag for the derived class should use the same tag as the base class. The derived classes, though, should use a different BaseName from the base class. For example:

anmAnimal (base class)
anmZebra (derived class of anmAnimal)
anmElephant (derived class of anmAnimal)

This logic of naming derived classes is used with forms, which are all derived from the pre-defined Form base class and use the frm tag. If a variable is defined to be of the type of the base class, then use the tag, as usual. For example:

Dim anmArbitrary As anmAnimal
Dim frmNew As Form

On the other hand, if you define a variable as an instance of a derived class, include the complete derived class name in the variable name. For example:

Dim anmZebraInstance As anmZebra
Dim anmElephantExample As anmElephant
Dim frmCustomerData As frmCustomer

Constructing Procedures

VBA procedures require you to name various items: procedure names, parameters, and labels. These objects are described in the following sections.

Constructing Procedure Names

VBA names event procedures, and you cannot change them. You should use the capitalization defined by the system. For user-defined procedure names, capitalize the first letter of each word in the name. For example:

cmdOK_Click
GetTitleBarString
PerformInitialization

Procedures should always have a scope keyword, Public or Private, when they are declared. For example:

Public Function GetTitleBarString() As String
Private Sub PerformInitialization

Naming Parameters

You should prefix all parameters in a procedure definition with ByVal or ByRef, even though ByRef is optional and redundant. Procedure parameters are named the same as simple variables of the same type, except that arguments passed by reference use the prefix "r". For example:

Public Sub TestValue(ByVal intInput As Integer, ByRef rlngOutput As Long)
Private Function GetReturnValue(ByVal strKey As String, ByRef rgph As Glyph)
As Boolean

Naming Labels

Labels are named using upper and lower case, capitalizing the first letter of each word. For example:

ErrorHandler:
ExitProcedure:

Prefixes

Prefixes modify an object tag to indicate more information about an object.

Arrays of Objects Prefix

Arrays of an object type use the prefix "a". For example:

aintFontSizes
astrNames

Index Prefix

You indicate an index into an array by the prefix i, and for consistency the data type should always be a long. You may also use the index prefix to index into other enumerated objects, such as a collection of user-defined classes. For example:

iaintFontSizes
iastrNames
igphsGlyphCollection

Prefixes for Scope and Lifetime

Three levels of scope exist for each variable in VBA: Public, Private, and Local. A variable also has a lifetime of the current procedure or the lifetime of the object in which it is defined. Use the prefixes in Table 2 to indicate scope and lifetime.

Table 2: Scope prefixes

You also use the "m" and "g" constants with other objects, such as constants, to indicate their scope. For example:

intLocalVariable
mintPrivateVariable
gintPublicVariable
mdblcPi

VBA allows several type declaration words for backward compatibility. The older keyword "Global" should always be replaced by "Public", and the "Dim" keyword in the General Declarations section should be replaced by "Private".

Other Prefixes

Table 3 lists and describes some other prefixes:

Table 3: Other commonly-used prefixes

Here are some examples:

castrArray
hWndForm

Suffixes

Suffixes modify the base name of an object, indicating additional information about a variable. You'll likely create your own suffixes that are specific to your development work. Table 4 lists some generic VBA suffixes.

Table 4: Commonly-used suffixes

Here are some examples:

iastrNamesMin
iastrNamesMax
iaintFontSizesFirst
igphsGlyphCollectionLast
lngCustomerIdCnt
varOrderIdCnt

File Names

When naming items stored on the disk, no tag is needed because the extension already gives the object type. For example:

Test.Frm (frmTest form)
Globals.Bas (globals module)
Glyph.Cls (gphGlyph class module)

Host Application and Component Extensions Tags

Each host application for VBA, as well as each component that can be installed, has a set of objects it can use. This section defines tags for the objects in the various host applications and components.

Access

Table 5 lists Access object variable tags. Besides being used in code to refer to these object types, these same tags are used to name these kinds of objects in the form and report designers.

Table 5: Access object variable tags

Some examples:

txtName
lblInput

For ActiveX custom controls, you can use the tag ocx as specified in Table 5 or more specific object tags that are listed later in this document in Tables 14 and 15. For an ActiveX control that doesn't appear in the Tables 14 or 15, you can either use ocx or invent a new tag.

DAO Objects

DAO is the programmatic interface to the Jet database engine shared by Access, Visual Basic, and Visual C++. The tags for DAO objects are shown in Table 6.

Table 6: DAO object tags

Here are some examples:

rstCustomers
idxPrimaryKey

Table 7 lists the tags used to identify types of objects in a database.

Table 7: Access Database Explorer object tags

If you wish, you can use more exact tags or suffixes to identify the purpose and type of a database object. If you use the suffix, use the tag given from Table 7 to indicate the type. Use either the tag or the suffix found along with the more general tag, but not both. The tags and suffixes are shown in Table 8.

Table 8: Specific object tags and suffixes for Access Database Explorer objects

Here are some examples:

tblValidNamesLookup
tlkpValidNames
fmsgError
mmnuFileMnu

When naming objects in a database, do not use spaces. Instead, capitalize the first letter of each word. For example, instead of Quarterly Sales Values Table, use tblQuarterlySalesValues.

There is strong debate over whether fields in a table should have tags. Whether you use them is up to you. However, if you do use them, use the tags from Table 9.

Table 9: Field tags (if you decide to use them)

Visual Basic Objects

Table 10 shows the tags for Visual Basic 6.0 objects.

Table 10: Visual Basic object tags

ActiveX Data Objects

Office 2000 provides the ActiveX Data Objects library. Table 11 lists the recommended tags for this version of ADO.

Avoiding Object Confusion

Many of the ADO, ADOX, and JRO tags overlap with existing DAO tags. Make sure you include the object library name in all references in your code, so there's never any possibility of confusion. For example, use

Dim rst As ADODB.Recordset

or

Dim cat As ADOX.Catalog

rather than using the object types without the library name. This will not only make your code more explicit and avoid confusion about the source of the object, but will also make your code run a bit faster.

Table 11: ADO Object tags

ADO Ext. for DDL and Security (ADOX)

In order to support DDL and security objects within Jet database, Microsoft provides ADOX, an additional ADO library of objects. Table 12 lists tags for the ADOX objects.

Table 12: ADOX Object tags

Jet and Replication Objects

In order to support Jet's replication features, ADO provides another library (JRO). Table 13 lists suggested tags for the JRO objects.

Table 13: JRO object tags

Common Control Objects

Windows has a set of common controls that are accessible from VBA. Table 14 lists the tags for objects created using these controls.

Table 14: Microsoft Common Control Object tags.

Other Custom Controls and Objects

Finally, Table 15 lists the tags for other commonly-used custom controls and objects.

Table 15: Tags for commonly-used custom controls

Summary

Using a naming convention requires a considerable initial effort on your part. The payoff comes when either you or another programmer has to revisit your code at a later time. Using the conventions given here will make your code more readable and maintainable.