Visual Basic Programming Standards
Visual Basic Programming Standards
PROGRAMMING STANDARDS ARE USED TO HELP PROGRAMMERS create a consistent structure, coding style, and logic of an application.
Standards help a programmer create code that’s easy to read, unambiguous, and easily maintained by other programmers in the organization.
Reasons for Naming Conventions
There are many reasons programming standards are created. Most mainframe
shops have had programming standards for years. Unfortunately, most PC programmers
have forgotten or have never worked in a formal programming shop,
and they often overlook this important step in application development.
Creating a programming standard does not limit your creativity, as most programmers
seem to think. Instead, it helps you focus your creativity where it’s really
needed. You can concentrate on the program itself instead of having to always
think about what name to give a variable. Think about the Windows environment
(or even the Macintosh)—every program written for Windows has a consistent look
and feel. This is why users like using Windows programs, because they don’t have
to learn everything about how a new program works—they already know how to
use most of the new program’s features. By using standards in your programming,
you can also keep the programmer “look and feel” consistent. This means you
spend less time figuring out what the variables are or how many indents a programmer
used, and you can focus more on the logic of the program.
The use of standards can lead to reduced maintenance costs due to a consistent
look and feel. This means you can move from one project to another very easily—
even one someone else wrote—and immediately read and understand the code.
Environment Options
To start, you should make sure every programmer’s Visual Basic environment is consistent,
or if you are working alone, make sure that you at least set the following
defaults. Visual Basic lets you set defaults for the development environment.
Option Explicit
Declaring all variables in your code saves programming time by reducing the number
of bugs caused by typos and undeclared variables. For example, the following
variables all look the same: aUserNameTmp, sUserNameTmp, and sUserNameTemp.
If you don’t set the Option Explicit statement at the top of every module, these
different variable names could all have potentially different values. At runtime, you
check the value of the sUserNameTmp variable when you really wanted to be
checking the value of the variable sUserNameTemp. If you set the Option
Explicit statement at the top of the module, the compiler will inform you of the
typo. If you don’t set the Option Explicit, the runtime engine will simply create
another variable on-the-fly and assign a zero value to that variable. This can lead to
a bug that’s very hard to track down.
Custom Control Naming Conventions
An important part of any Visual Basic program is the controls placed on a form. All
similar custom controls should have a common prefix. For example, text boxes
should start with txt, and labels should start with lbl. Table A.2 shows the recommended
control name prefixes for most of the controls in the Visual Basic environment.
Menu Naming Conventions
Just like custom controls, all the various menus you create should also use appropriate
prefixes (see Table A.3). The prefix mnu should be used on all menus. This prefix
should be followed by the caption of the menu. For each pull-down menu under
the main menu item, use the first letter of top-level menu.
When this convention is used, all members of a particular menu group are listed
next to each other in the Object drop-down list boxes (in the Code and Property
windows). In addition, the menu control names clearly document the menu items
to which they’re attached.
Naming Conventions for Other Controls
For new controls not listed so far, try to come up with unique three-character prefixes.
Note, however, that it’s more important to be clear than to stick to a threecharacter
convention.
For derivative controls, such as an enhanced list box, extend the preceding prefixes
so that there’s no confusion over which control is really being used. A lowercase
abbreviation for the manufacturer could be added to the prefix. For example, a
Crescent QuickPak Professional text box control could be named ctxtFirstName.
Third-party Controls
Each third-party control used in an application should be listed in the application’s
overview comment section, providing the prefix used for the control, the full name
of the control, and the name of the software vendor (see Table A.4).
Variable Data Type Prefixes
Table A.6 defines the standard variable data types in Visual Basic. These prefixes
should be used when naming the variables in your program. Avoid the use of the
Visual Basic suffixes (%, &, #, and so on) at all costs.
Scope Prefixes
A variables scope refers to the locations within your application that a particular
variable may be read or modified. For example, a local variable is one declared
within a Sub...End Sub or Function...End Function. This variable may only
be read or modified while code is executing within the Sub...End Sub statements.
A module-level variable, on the other hand, may be read and modified from
any procedure or function within the same module. Global or public variables may
be referenced from any procedure or function within the same project. Table A.7
lists the common scope prefixes you should use.
Class Naming
When creating your own user-defined classes, you need to be aware of who your
target user will be for that class. If you’ll be exposing that object and its properties
through an Automation Server, you should not use Hungarian notation.
Nonprogrammer types will not understand this type of notation.
It’s recommended that you create Property Get/Let/Set procedures for every
variable used within the class you want to give the user access to. Use Hungarian
notation on all private data but do not use it on the Property Get/Let/Set procedures.
When naming your class modules, keep in mind that you need to give each public
class a descriptive name that the user can understand. If you’re creating an internal
class that’s only used within your program, use the prefix cls or maybe just C (see
Table A.8).
Commenting Your Code
Each procedure and function should 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 yet, erroneous
comments. The code itself and any necessary inline or local comments
should describe the implementation.
Parameters passed to a routine should be described when their function is not obvious
and when the routine expects the parameters to be in a specific range.
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.
Each nontrivial variable declaration should include an inline comment describing the
use of the variable being declared.
Variables, controls, and routines should be named clearly enough that inline commenting
is only needed for complex or nonintuitive implementation details.
An overview description of the application, enumerating primary data objects, routines,
algorithms, dialog boxes, 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.
Scope
Variables should always be defined with the smallest scope possible. Global variables
can create enormously complex state machines and make the logic of an
application extremely difficult to understand. Global variables also make the reuse
and maintenance of your code much more difficult. Variables in Visual Basic can
have the following scope, as detailed in Table A.9.
Global Variables
If you must use global variables, it’s good practice to declare all of them in a single
module and group them by function. Give the module a meaningful name that
indicates its purpose, such as GLOBAL.BAS.
With the exception of global variables, 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.
In addition, you should pass arguments to subs and functions using ByVal, unless
you explicitly want to change the value of the passed argument.
Write modular code whenever possible. For example, if your application displays a
dialog box, put all the controls and code required to perform the dialog box’s task
in a single form. This helps keep the application’s code organized into useful components
and minimizes its runtime overhead.
Summary
Programming standards can make the job of the maintenance programmer much
easier. Because 90 percent of the time you’ll be the maintenance programmer, you
should try to follow some programming standards when designing your applications.
Programming standards are absolutely essential in a multiprogrammer shop.