Visual Basic Naming Conventions
The choice of names for code members can have a considerable influence on the ease of
understanding and maintenance costs of your Visual Basic source code. The following
techniques are used by many professional Visual Basic programmers to write code which
is easier to read, understand and maintain.
What's in a name?
To read and understand code easily, code must be written consistently to conform to agreed
coding standards. Readers familiar with the coding standards can then understand the code more
easily thereby leading to lower maintenance and development costs. Consider the following
example VB code snippet:
x = a(1,3)
The brevity of the names chosen for the code members above ("x" and "a")
make it difficult to understand what the code members are and what they are used for. It's
also not clear whether "x" is being assigned the result of a function call
or the value held in an array item. If "a" is a function, what does it do? What data
type does it return? The name offers us no clues. Likewise, what is "x" used for, what
data type is it and what is its scope? Again, no clues.
If suitable naming conventions had been enforced at the time this code was written, it might
have been much easier to understand. Such is the need for good naming conventions and the ability
to enforce them effectively.
What must a name convey?
For a name to be meaningful in Visual Basic, the name must immediately convey at least two
essential pieces of information about a code member: what it is, and what it is used for.
A good name conveys the following information about a Visual Basic code member:
- Code member type (e.g. variable, constant, function etc.).
- Code member usage (i.e. what it does or what it is used for).
- Scope (if applicable to the code member type).
- Data type (if applicable to the code member type).
The Recipe For Good Names
Like good food usually consists of more than one ingredient, so too do good code member names.
This is achieved by assembling individual names from one or more constituent elements, each of
which is used to convey specific information about the code member such as: what type of code
member it is, what it is being used for and possibly what data type and scope it has.
Most names for Visual Basic code members can be constructed from the combination of the
following elements:
- [Scope][Type]Body
Tip
Consistent use of naming conventions can significantly reduce the chance of name clashes
which can be the cause of unexpected bugs.
Body Element Names
All code member names have a 'Body' element that is used to describe the intended use
for a code member such as what it does or what information it holds. The case used for the
body element name, and whether or not underscore characters are used, can also be used to
convey meaning about a code member. For example, the body element of a variable name
used to hold an account number might be set to 'AccountNumber' while the body
name of a constant used to hold an account number might be set to 'ACCOUNT_NUMBER'.
Tip
Abbreviations should generally be avoided when constructing the body element
of a code member name unless an agreed (domain specific) abbreviation can be defined and
used consistently.
Type element tags are often used to prefix code member body element names to convey
specific information about a code member such as what type of code member it is
or its data type. The use of type element tags is dependent on the type of the code
member being named and therefore type element tags are further divided into
data type tags, control tags and file type tags.
The following data type tags represent the tags commonly used
to express the data type of a code member:
| Data Type Tag |
Data Type / Meaning |
Example |
| a |
Used to prefix other data type tags to indicate an array. |
asNames() |
| b |
Boolean |
bFinished |
| byt |
Byte |
bytChar |
| col |
Collection |
colAddressLines |
| ctl |
Control |
ctlElement |
| cur |
Currency |
curAmount |
| d |
Double |
dInvoiceTotal |
| dt |
Date |
dtInvoiceDate |
| e |
Used for instances of enumerations. |
eDayOfWeek |
| err |
Error |
errInfo |
| evt |
Used for WithEvents variable declarations. |
evtToolbar |
| h |
Handle (Long) to a Windows object. |
hWnd |
| i |
Integer |
iCount |
| l |
Long |
lSize |
| obj |
Object (also used for instances of named classes) |
objCustomer |
| s |
String |
sCustomerName |
| f |
Single |
fWidth |
| udt |
User-defined type |
udtEmployeeRecord |
| vnt |
Variant |
vntArgumentList |
Tip
Do not use the Visual Basic data type suffix characters such as '%' for integer.
The use of 'Scope' element tags is dependent on the type of the code member being named.
Scope element tags are often used to prefix code member names to describe the
scope level of a code member.
Scope tags are applicable to a number of different code member types and are used to
denote the scope (e.g. local, module-level, global) of a code member. The following table
lists the scope tags used by many Visual Basic programmers:
| Scope Tag |
Meaning |
Example |
| g_ |
Global (Public) |
g_lAccountNumber |
| m_ |
Module-level |
m_dAccountBalance |
| <none> |
Local |
dOrderValue |
| st_ |
Local (static) |
st_sLastInvoiceID |
Naming Visual Basic Code Members
Visual Basic supports the following code members which require a name:
Note: Naming conventions for line labels are not covered by this article. Please
refer to the quality zone article on Visual Basic Error Handling
for advice on choosing line label names.
Arguments are defined as part of 'Declare' statements, 'Event', 'Sub', 'Function' and 'Property'
procedure definitions. An argument name should express the argument's calling convention (ByRef or
ByVal), data type and intended use.
Argument names are constructed from the following elements:
- [Scope][Data Type]Body
Scope |
The following scope tags must be used when naming arguments:
|
| |
| Scope Tag |
Scope / Meaning |
Example |
| r_ |
Argument is passed by reference (ByRef) |
r_dOrderTotal |
| v_ |
Argument is passed by value (ByVal) |
v_sCustomerName |
|
Data Type |
The data type tag used within the argument name must be selected from the list of valid
data type tags based on the declared data type of the argument.
|
Body |
The body element of argument names must always begin with a capital letter, use
mixed case and contain no underscore characters.
|
Example |
v_sCustomerName |
Constant names are constructed from the following elements:
- [Scope][Data Type]Body
Scope |
The scope tag used within the constant name must be selected from the list of valid
scope tags based on the declared scope of the constant.
|
Data Type |
The data type tag used within the constant name must be selected from the list of valid
data type tags based on the declared data type of the constant.
|
Body |
The body element of constant names must always be upper case and may contain
underscore characters.
|
Example |
m_sMODULE_NAME |
Control names are constructed from the following elements:
- [Control Tag]Body
Control Tag |
The control tag used within the control name must be selected from the list of valid
control tags based on the class of the control.
|
Body |
The body element of control names must always begin with a capital letter, use
mixed case and contain no underscore characters.
|
Example |
txtCustomerName |
The following table lists the control tags used by many Visual Basic programmers:
| Control Tag |
Control Class |
| ani |
MSComCtl2.Animation |
| cbo |
VB.ComboBox |
| chk |
VB.CheckBox |
| cht |
MSChart20Lib.MSChart |
| cmd |
VB.CommandButton |
| ctl |
(Unknown class ProgID) |
| data |
VB.Data |
| dir |
VB.DirListBox |
| dlg |
MSComDlg.CommonDialog |
| drv |
VB.DriveListBox |
| dtp |
MSComCtl2.DTPicker |
| file |
VB.FileListBox |
| fra |
VB.Frame |
| frm |
VB.Form |
| hsb |
VB.HScrollBar |
| img |
VB.Image |
| imgcbo |
MSComctlLib.ImageCombo |
| ils |
MSComctlLib.ImageList |
| lbl |
VB.Label |
| lin |
VB.Line |
| lst |
VB.ListBox |
| lvw |
MSComctlLib.ListView |
| medt |
MSMask.MaskEdBox |
| mnu |
VB.Menu |
| mvw |
MSComCtl2.MonthView |
| ole |
VB.OLE |
| opt |
VB.OptionButton |
| pb |
MSComctlLib.ProgressBar |
| pic |
VB.PictureBox |
| rtxt |
RichTextLib.RichTextBox |
| shape |
VB.Shape |
| tab |
TabDlg.SSTab |
| tbs |
MSComctlLib.TabStrip |
| tmr |
VB.Timer |
| txt |
VB.TextBox |
| sb |
ComctlLib.StatusBar |
| slide |
ComctlLib.Slider |
| stb |
MSComctlLib.StatusBar |
| tb |
ComctlLib.Toolbar |
| tlb |
MSComctlLib.Toolbar |
| tvw |
MSComctlLib.TreeView |
| upd |
MSComCtl2.UpDown |
| vsb |
VB.VScrollBar |
| wbr |
SHDocVwCtl.WebBrowser |
There are two aspects of enums which require consideration when naming
code members: the name of the enum definition itself and the names of the
enum members. A further consideration may also be applied based on the intended
use of the enum such as whether the enum will represent a list of results
used for function return codes.
Enum definition names are constructed from the following elements:
- [Prefix][Body]Constants
Prefix |
The prefix element of enum names must always be at least two characters,
lower case and contain no underscore characters.
|
Body |
The body element of enum names must always begin with a capital letter, use
mixed case, contain no underscore characters and end with the literal 'Constants'.
|
Example |
etEmployeeTypeConstants |
Enum member names are constructed from the following elements:
- [Prefix]Body
Prefix |
The prefix used for the member name must be the same as the prefix used
for the enum definition name.
|
Body |
The body element of member names must always begin with a capital letter, use
mixed case and contain no underscore characters.
|
Example |
etPermanent = 1 |
Procedure names are defined as part of 'Declare' statements, 'Event', 'Sub',
'Function' and 'Property Get/Let/Set' definitions.
Procedure names are constructed from the following elements:
- [Body]
Body |
The body element of procedure names must always begin with a capital letter, use
mixed case and contain no underscore characters. It is essential that procedure names
are precise and neither overstate nor understate the role of the procedure.
|
Example |
Public Function CalculateIncomeTax() As ITC_RESULT |
Tip
Avoid use of 'Scope' and 'Type' elements when constructing names for procedures. It is
not unknown for the scope of procedures to change over time (often to add increased
visibility i.e. 'Private' becomes 'Public' or 'Friend'). Procedures can also return
more than one value if arguments are passed by reference.
There are a number of different aspects of projects which require consideration
when naming code members: the 'Name' attribute of the project, the name of the project
(VBP) source file, the filename of the compiled application
or component and any associated help file.
The project name attribute is constructed from the following elements:
- [Body]
Body |
The body element of project names must always begin with a capital letter, use
mixed case and contain no underscore characters.
|
Example |
MyApp, MyApp.VBP, MyApp.Exe, MyApp.chm |
Tip
Choose the project 'Name' attribute carefully and then use the same name for the project
source file, compiled component name and help filename.
There are a number of different aspects of projects which require consideration
when naming source files: the 'Name' attribute of the file and the filename for the
source file.
The source file 'Name' attribute is constructed from the following elements:
- [File Type][Body]
File Type |
The following file type tags must be used when specifying file 'Name' attributes:
|
| |
| File Type Tags |
Type / Meaning |
| frm |
Form module (.frm). |
| mod |
Code module (.bas). |
| cls |
Private class module (.cls). |
| <none> |
Public class module (.cls). |
| I |
Public class module (.cls) used to define an interface only. |
| dsr |
Designer module (.dsr). |
| uctl |
User control module (.ctl). |
| udoc |
User document module (.dob). |
|
Body |
The body element of source file 'Name' attributes must always begin with a capital letter, use
mixed case and contain no underscore characters.
|
Example |
frmCustomerDetails |
Tip
Choose the source file 'Name' attribute carefully and then use the same name for the
source file filename. Always stick to the Visual Basic default for source file extensions (e.g. '.frm' for
forms, '.cls' for classes etc.) when naming source files.
There are two aspects of user-defined types which require consideration when naming
code members: the name of the user-defined type definition itself and the names of the
user-defined type members.
User-defined type definition names are constructed from the following elements:
- [Body]Type
Body |
The body element of user-defined type names must always begin with a capital letter, use
mixed case, contain no underscore characters and end with the literal 'Type'.
|
Example |
EmployeeType |
User-defined type member names are constructed from the following elements:
- [Data Type]Body
Data Type |
The data type tag used within the member name must be selected from the list of valid
data type tags based on the declared data type of the member.
|
Body |
The body element of member names must always begin with a capital letter, use
mixed case and contain no underscore characters.
|
Example |
sEmployeeID As String * 5 |
Variable names are constructed from the following elements:
- [Scope][Data Type]Body
Scope |
The scope tag used within the variable name must be selected from the list of valid
scope tags based on the declared scope of the variable.
|
Data Type |
The data type tag used within the variable name must be selected from the list of valid
data type tags based on the declared data type of the variable.
|
Body |
The body element of variable names must always begin with a capital letter, use
mixed case and contain no underscore characters.
|
Example |
m_sCustomerID |
Enforce Naming Conventions
Having naming conventions is one thing, enforcing them successfully is another.
To ensure naming conventions are implemented correctly you may wish to extend your VB coding
standards to include rules applicable to your naming conventions and to include
naming conventions as a topic to be covered during peer code reviews.
Find out how VB Law can quickly help define and enforce VB naming
conventions. VB Law has inbuilt support for scope tags, data type tags and control tags and comes with
sample rules to enforce naming conventions for all of the code members described in this article.
Visit our downloads page and trial VB Law for free today.
|
