• Naming Conventions: A Primer
• Structuring Object Names
  • What Is a Prefix?
  • What Is a Tag?
  • What Is a Base Name?
  • What Is a Qualifier?
  • What Is a Suffix?
• Naming Conventions for VB Objects
  • Tags for Project Objects
  • Tags for Module Objects
  • Tags for Form Control Objects
  • Naming Menus
• Naming Conventions for VBA Objects
  • Rules for VBA Object Base Names
  • VBA Object Base Name Lengths
  • Compound VBA Object Base Names
  • Using Tags with VBA Objects
  • Tags for Variables
  • Creating OLE Automation Variables
  • Tags for Remote Data Objects
  • Prefixes for Variables
  • Naming Constants
  • Tags and Prefixes for Procedures
    • Prefixes for Procedures
    • Tags for Procedures
  • VBA Object Name Examples
• Naming Conventions for Jet Objects
  • Rules for Base Names
  • Base Name Length Limits
  • Compound Base Names
  • Field Base Names
  • Ordering Base Name Elements
  • Tags for Jet Objects
  • Prefixes for Database Objects
  • Database Object Name Examples
• Creating Your Own Tags
• VBA Coding Conventions
  • Common Practices
  • Code Comments
  • Trapping Errors
• Standardized Abbreviations
• Standardized Terminology
• How to Get the Leszynsiki Naming ConventionsLNC
• Sending in Your Feedback
• The Fine Print

- Appendix B -
The Leszynski Naming Conventions for Microsoft Visual Basic

By: Stan Leszynski

Developers by nature have this love/hate thing about naming conventions. Such standards are often seen as slowing the development process, increasing the size of object names and files, and stifling true programming creativity. And yet, without order, the laws of entropy invariably draw every project toward incoherent "spaghetti code" and/or "spaghetti objects." Thus, few developers would argue against the need for an ordered approach to development, but they want the system that is least intrusive.

Sorry, but you can't have it both ways! A system that is comprehensive and applied consistently will also by nature be mildly intrusive. If you want to apply a naming convention to your objects, you will incur a penalty of a few keystrokes every time you type an object name. However, the small pain of extra keystrokes certainly produces a large gain.

Creating your own naming conventions takes research, group effort, and testing. To complicate matters, there are several different approaches you can take when naming objects. For a complete discourse on designing your own naming conventions, see the book Access Expert Solutions by Stan Leszynski, published by Que Corporation.

In this appendixdocument, I detail for you the Leszynski Naming Conventions ("LNC"), a set of standardized approaches to naming objects during Visual Basic ("VB") development. These naming conventions were born of necessity, since some members of my staff spend all day in VB development, year after year. They were also born of a different need—a void that existed in the marketplace due to a lack of consensus about development styles among leading VB application developers.

Our Visual Basic conventions are tightly linked with our conventions—now also called LNC, formerly called L/R—for Microsoft Access for Windows 95 and the Microsoft Jet database engine. The L/R conventions for Access were distributed broadly, with over 500,000 copies in print, and became the most widely accepted conventions in the Access user community. Over the last few years, we have received feedback about L/R from hundreds of developers and companies, and have tried to accommodate some of their input, as well as our ongoing experiences, into LNC documents for both Access and Visual Basic.

LNC assumes that most VB developers also work with other Microsoft development tools: Access, Excel, SQL Server, and others. Microsoft's development products have more in common in their '95 versions than in any previous iterations. Consequently, this VB style dovetails with the LNC development style detailed in the Leszynski Naming Conventions for Microsoft Solution Developers, a separate document which covers all of Microsoft's application development products.

This document includes Jet conventions and examples in recognition of the fact the Jet has become the default database engine for many VB developers. More detailed style information for working with Access and Jet is found in the Leszynski Naming Conventions for Microsoft Access document.

I use the terms naming conventions, style, and LNC interchangeably throughout this document.

Naming Conventions: A Primer

Naming conventions are one of the foundation elements of your overall development style. We developed our naming conventions primarily to achieve four objectives:

• To be able to quickly understand an application's structure and code by making object names more informative.
  
  
• To simplify team development of applications by creating a standardized vocabulary for all team members.
  
  
• To improve our ability to work with VB and Jet objects, including enforcing object name sort orders, creating self-documenting program code, and enhancing find and replace capabilities.
  
  
• To increase our ability to create tools for our VB development work, and to create code libraries across various VBA platforms.
  
  

To meet these objectives, we create and apply consistent naming conventions to these application objects:

• Class modules
  
  
• Forms
  
  
• Form controls
  
  
• Modules
  
  
• Procedures
  
  
• Variables
  
  
• Constants
  
  
• User-defined types
  
  
• Database tables
  
  
• Database table fields
  
  
• Database queries
  
  

---

The term database in the preceding listthis table refers to using VB against Jet and SQL Server data. While Jet is discussed in this document, naming conventions for NT SQL Server are documented in the Leszynski Naming Conventions for Microsoft Solution Developers paper.

---

Object names are the foundation on which your entire application is built, so they are almost impossible to change once development has begun in earnest. Therefore, you probably won't find it cost or time-efficient to retrofit these conventions into your existing applications. For new applications, however, you should apply these naming conventions consistently from the moment you create your first object in a new project file.

LNC relies primarily on leading tags—several characters placed before an object's name (for example, frmCust). This approach is sometimes referred to as Hungarian notation. (The term Hungarian refers to the nationality of Charles Simonyi, a programmer at Microsoft who wrote a doctoral thesis in the 1980's called "Program Identifier Naming Conventions"). Leading tags provide several benefits:

• The first thing you see about an object when you see its name is the leading type tag, which is often more important than the name itself.
  
  
• Leading tags drive the ordering of object names in Access, Jet, VB, and VBA object lists, sorting by type and then by base name.
  
  
• Leading tags are consistently located in the same place in an object's name, making them easier to find by parsers and other tools.
  
  

If you are averse to Hungarian notation for some reason and prefer trailing tags, LNC will still work for you. However, LNC prescribes no standard for locating and punctuating trailing tags. You will have to decide if they are offset with an underscore (Order_fmdi), or by capitalization (OrderFMdi), or by some other technique. Remember also that you should be consistent throughout your style, so if you use trailing tags for objects, you will need to use them when writing VB code as well.

For purposes of this document, we have created the standardized terminology in Table B.1 for grouping objects. We will use these group names when discussion naming conventions.

Structuring Object Names

In LNC, object names are constructed using this syntax:

[prefix(es)] tag [BaseName] [Qualifier] [Suffix]

The brackets indicate optional syntax elements—do not include them in your actual object names. Notice that the tag element is required even though the BaseName is not in some cases. These options will be explained later in this document. Note in the syntax diagram that the case of each element reflects its case in actual use. The element tag is in lower case since the tags themselves are always lower case. Table B.2 shows sample object names using these constructions.

What Is a Prefix?

A prefix is an identifier that precedes a tag and clarifies it narrowly. Prefixes describe one or more important properties of an object. For example, a Long variable that is public in scope (declared Public) has a prefix p, as in plngRecNumMax. Prefixes are one or two characters long and in lower case. Multiple prefixes can be used together on one object, as in ialngPartNum, where i and a are both prefixes.

What Is a Tag?

A tag is a multi-character string placed against an object base name to characterize it. In object-oriented programming terms, the tag is basically an identifier for the class. Note that the word class here refers to a naming convention construction, not an exact object model construction. For example, there is only one Query (or QueryDef) class object in Jet, and the data action (delete, update, and so on.) is determined by its SQL statement, not its class. Nevertheless, LNC prescribes several tags for this one Jet class.

Tags are three or four characters long for readability and to allow for the hundreds of combinations necessary as the Microsoft Office object model grows over time. They are always to the left of the base name and in lower case, so that your eye reads past them to the beginning of the base name.

A tag is created to mnemonically represent the word it abbreviates, such as "frm" for "form". However, some tags may not seem fully mnemonic for three reasons. First, the perfect (or obvious) tag for a particular new object may already be assigned to another object in a product that existed previously. Secondly, where common objects (objects with similar properties and usage) exist in multiple Microsoft applications, the tag for one may be used to represent similar objects in other products, even if the names are different. For example, Visual Basic Shape objects and Access Rectangle objects share the tag shp in LNC, since they are very similar objects structurally. Finally, there may not be such a thing as an "obvious" tag, so a suitable one may be chosen from a body of several reasonable candidates.

What Is a Base Name?

The base name is the starting point when you name a particular object—the name you would use anyway if you had no naming conventions. The LNC guidelines for creating base names are driven by a set of rules stated later in this document.

What Is a Qualifier?

A qualifier is an extension following the base name that provides context to the specific use of an object. Unlike prefixes, which detail properties of the object (for example, that the variable has public scope), qualifiers describe how the object is being used in a context. For example, plngRecNumMax is obviously the maximum record number, in an application that could also have variables for the minimum (plngRecNumMin) and current (plngRecNumCur) record numbers. Qualifiers are short and written with mixed upper and lower case, as in the examples in Table B.3.

What Is a Suffix?

Suffix elements provide specific information about the object and are used only as "tie-breakers" when more detail is required to differentiate object names that could otherwise legitimately be identical. Suffixes are the only element in the syntax diagram where LNC does not suggest standardized values. You will create suffix items as needed by your company, development team, or application. For example, a series of queries that summarized the best sales performance by state would need the state name in each object name to properly qualify it, as in qsumSalesPerfBest_AK. Placing the state name at the very end of the name as a suffix item allows the entire collection of related queries to sort together, like this:

qsumSalesPerfBest_AK



qsumSalesPerfBest_AL



...



qsumSalesPerfBest_WY

Since the suffix is the last piece of information on a name, it can be easier for the eye to find if delimited from the rest of the object name with an underscore, as shown, but this convention is optional.

Naming Conventions for VB Objects

The building blocks of your application are its objects. When creating base names for VB objects, you should give careful consideration to the purpose of the object, the approaches used to name associated objects, and the rules of thumb that follow for naming objects.

Tags for Project Objects

Your Visual Basic project can consist of many files, and good development style often dictates that you keep all files for a project in the same directory. However, with the advent of long file names, I have found it helpful to give each project a unique abbreviation and apply the characters as a tag for files in the project. This helps me to:

• Track project files that might bccome intermingled with other files.
  
  
• Delineate project files from other application files in the same directory.
  
  
• Differentiate project-specific files from company library files in the same project.
  
  
• Create a server tag that can be used if the application becomes an OLE server.
  
  

Tags for Module Objects

Table B.4 lists the tags for Visual Basic module objects.

Tags for Form Control Objects

VB applications usually consist of many forms. While it is acceptable to tag every form with frm, LNC provides the opportunity to be more specific about the nature of each form, as seen in Table 5. While object name sort order is not enforced in the Project window (Dear Microsoft, I wish you treated object names with greater importance than file names in the Project window...), viewing forms through the Object Browser is easier with meaningful object tags.

Table B.6 lists the tags for control objects on forms, and Table B.7 provides tags for critical OLE control types. VBA code written behind forms using this convention will reflect a control's type in its event procedure names (for example cboState_AfterUpdate). The automatic sorting provided by this notation in the VB IDE can be very helpful during development. All control tags are three characters long.

The trailing 3 on the tags for 3D controls is included for backward compatibility with VB3 projects using THREED.VBX, but is not required by LNC for controls in new VB4 projects.

Some conventions attempt to catalog or create tags for third-party VBX and OLE controls. Such an effort is beyond the scope of this document—I take responsibility here only for helping you use controls that are part of a VB developer's standard tool set or are created by my company. A starting point if you are interested in tags for third-party controls is the document "Microsoft Consulting Services Naming Conventions for VB" on the Microsoft Developer Network CD subscription.

Naming Menus

Most VB coders use a standard menu naming convention already, which consists of the tag mnu before a menu control base name built of the menu's options, as in mnuFileExit. This technique will cause menu options to sort in a very distinct order in the property dialog, and is acceptible for LNC.

In addition to standard bar and drop-down menu combinations, you can create pop-up or "shortcut" menus in VB 4. LNC suggests that you prefix these objects with the mct tag to keep the menu items grouped together when sorted. "Shortcut" is the term used by Windows 95 for context menus, so I prefer using it over the terms "pop-up menu" and "context menu" used in the VB documentation.)

Naming Conventions for VBA Objects

When creating base names for VBA objects, remember that the base name must be descriptive even in the absence of its tag. For some programmers, the syntax Dim I As Integer for a loop variable is quite acceptable. Within LNC, however, the variable named I would become iintLoop—an index integer variable to control a loop. Single-character variable names, especially without tags, are not allowed. Instead, create a list of short and standardized work variables to handle common daily needs (see tTable B.11 later in this document).

Rules for VBA Object Base Names

Crafting VBA object base names involves creating and following simple rules such as these:

1. Spaces are not allowed in any object name. Spaces create a multitude of problems with consistency, readability, and documentation. Where the readability of a space is required, use an underscore instead.
   
   
2. Object names begin with a letter and should include only letters, digits, and underscores.
   
   
3. Object names use mixed upper and lower case to add readability to the name.
   
   
4. The only syntax element that can have multiple capital letters is the base name. A qualifier or suffix begins with a single capital letter and then contains only lower case letters, unless it is an abbreviation, as in qsumSalesPerfBestUSA. If you need to clearly see the elements of a name (prefixes, tag, base name, qualifier, and suffix), LNC allows for—but does not require—underscores as separators, as in qsum_SalesPerf_Best_USA.
   
   
5. Object names are usually singular (Widget) rather than plural (Widgets).
   
   
6. An object's base name should include the base names of any objects it is built on, if practical.
   
   

Note that Rule 6 requires a reference in variable names to objects of any type that they relate to. For example, a Recordset variable created on tblCust should be named rstCust. Also, if a string array variable of part numbers astrPartNum had an Integer index variable, it should include the array's base name in its own sans tagging: iaintPartNum.

VBA Object Base Name Lengths

There is no LNC guideline limiting variable name length, but common sense dictates that variable names longer than 15 or 20 characters waste a lot of keystrokes at each use. For procedure names, the VBA module editor by default show the first 30 characters of a procedure name, so this number is suggested as the target maximum procedure name length.

Abbreviate VBA object base name elements wherever possible using a standardized abbreviation table such as the one in the section "Standardized Abbreviations." You can extend LNC by creating your own standard abbreviations. You should also create and use standardized terminology in your applications wherever possible, for examples see the section "Standardized Terminology."

Compound VBA Object Base Names

Procedure base names should follow the construction ObjectVerb, where the Object portion describes the primary object type affected (often the same as the primary argument), and Verb describes the action. This style sorts functions and subs by their target object when shown in ordered lists:

FormCtlHide



FormCtlShow



FormPropAdd



FormPropGet



FormPropSet

We find this sort order much more appealing than the more common alternative with VerbObject construction:

AddFormProp



GetFormProp



HideFormCtl



SetFormProp



ShowFormCtl

Using Tags with VBA Objects

In LNC, tags are required for the following VBA objects:

• Variables
  
  
• Type structures
  
  
• Constants
  
  

Optional tags also are available for some types of procedures.

In the syntax diagram earlier we noted that base names are optional in some constructions. When you are programming in VBA, the tag element is always required, but the base name is optional for variables local to a procedure. For example, a procedure that declares only one form object variable can legitimately use the variable name frm, which is a tag without a base name. Normally, however, I prefer more detail. Type structures, constants, and variables that have module-level or public scope must have both a tag and base name.

Tags for Variables

VBA variable tags are noted in Tables B.8 through B.10 below, grouped by type of variable.

---

In Table B.8, the Conditional Compilation Constant, Error, and User-Defined Type items are not true data types (created with Dim name As datatype), but rather are programming concepts. A Conditional Compilation Constant variable is a flag of type Boolean, an Error variable is a Variant created with the CVErr() function, and Types are unique user-defined constructs.

---

In Tables B.9 and B.10, tags for collection variables are made by adding s after the tag for the object type stored in the collection, as in usr for User and usrs for Users. The tags dyn, snp, and tbl for Dynaset, Snapshot, and Table objects are directly relevant to users of Jet 1 and Jet 2. Starting with Jet 3, these object types are allowed only as a subtype of Recordset variables, thus the Recordset tags rdyn, rsnp, and rtbl.

Even though we noted previously that a tag by itself is a legitimate variable name, a few variable tags shown (such as int) are VBA reserved words and will not compile in your procedures. Such tags require a base name.

Instead of using I and J as work variable names, use names that are still short but meaningful. For example, even iintI and iintJ are more descriptive than I and J, although I'd never use them. Instead, I try to keep a short list of handy work variables and reuse these variables where practical. Table B.11 suggests the LNC approach to commonly-used variables.

Creating OLE Automation Variables

Table B.12 lists entry points for common OLE server applications.

Note that variables for objects in the object hierarchy of a referenced type library can be dimensioned directly by class, as in this line:

Dim xlsapp As Excel.Application

Alternately, if the variable is created with late binding (that is as a generic object) rather than early binding, the prefix o is added to denote an object variable:

Dim oxlsapp As Object



Set oxlsapp = CreateObject("Excel.Application")

The naming convention for entry points into OLE server applications follows this syntax:

applicationtag [entrypointtag] primaryobjecttag BaseName

The item applicationtag is a three-character notation for the server application, and entrypointtag is three characters denoting the entry point used. The entrypointtag is optional and should be used when clarification is necessary (when variables for several entry points are declared in the same procedure), or when the entry point is not the standard Application object. The primaryobjecttag describes the ultimate class of the object (the one you intend to address with the variable). The BaseName is optional and clarifies the use of the variable, as with other VBA variables.

For example, the following code creates an Excel Range object and manipulates it.

Sub SalesCheck()



  Dim xlswksSales As Excel.Worksheet



  Dim xlsrngYTD As Excel.Range



  Set xlswksSales = GetObject("C:\Data\Sales.Xls", "Excel.Sheet")



  Set xlsrngYTD = xlswksSales.Range("YTDSales")



  If xlsrngYTD.Value < 100000 Then



    MsgBox "Sales are lame.", vbOKOnly, "Get to Work!"



  End If



  Set xlswksSales = Nothing



End Sub

In this example, the Range object is technically several layers deep in the application hierarchy, and a purely accurate combination of tags and code structure would yield this line of code, which actually runs:

Set xlsappwkbwksrngYTD = _



    xlsapp.ActiveWorkbook.Worksheets("Sales").Range("YTDSales")

In practice, of course, such nomenclature is unwieldy, and the shorter style is accurate but more friendly.

I prefer to show the server name in the variable declaration for clarity of code. While both lines below will run, the second is less ambiguous:

Dim xlsrng As Range



Dim xlsrng As Excel.Range

See the section "Creating Your Own Tags" for more discussion of OLE syntax. See the Leszynski Naming Conventions for Microsoft Solution Developers document for a complete listing of tags for Microsoft OLE servers and objects.

Tags for Remote Data Objects

The capabilities of the Remote Data Objects and the RemoteData control in VB 4 to work with ODBC data sources, and the structure of the objects themselves, makes it tempting to compare RDO and Jet objects. While there are many commonalities, there are also enough differences that we opted to create separate tags for use with RDO, as shown in Table B.13.

Prefixes for Variables

The prefixes for VBA variables can be categorized into two groups: prefixes for scope, and all other prefixes. Since the model for variable scope has changed somewhat in VB 4, I will discuss scope prefixes first. The following prefixes are ordered by increasing (broader) scope.

When used, scope prefixes always begin a variable name and precede any other prefixes.

In addition to scope, other characteristics of variables can be identified by prefixes:

A prefix provides a very detailed description of a variable. The number of allowable prefix combinations is limited, as shown in Table B.14.

Variables require a unique prefix when declared Public in a widely-distributed application to prevent name contentions. See the "Tags and Prefixes for Procedures" section for more information.

Naming Constants

VB 4 introduced some changes in the area of constants. The changes most relevant to naming conventions include these:

• A constant can now be assigned a data type when it is defined.
  
  
• All constants have been renamed and carry a tag of ac, db or vb to identify their primary functional area (Access, Jet, and VBA respectively).
  
  
• Constants can now be creating with the Variant data type.
  
  

When creating constants, use a scope prefix (if appropriate), the prefix c, and the suitable tag for the constant's data type. To properly synchronize the tag, the data type, and the value, do not let VB assign the type; always use the full "Const name As datatype" syntax.

Constants require a unique prefix when declared Public in a widely-distributed application to prevent name contentions. See the following section for more information.

Tags and Prefixes for Procedures

Whether and how to prefix and tag procedure names is a debatable subject. In general, this style neither requires nor encourages placing characters before a procedure name except, in the following situations.

Prefixes for Procedures

Procedures can have scope similar to that of variables—s (Static), m (Private), p (Public), or g (global Public). LNC allows, but does not encourage, the use of these scope prefixes on function names if they solve a particular need, and are used consistently throughout an application.

If you are creating code libraries for retail sale, for inclusion in the public domain, or for broad distribution in some other manner, LNC recommends that you prefix Public variables, constants, and procedures with a unique prefix identifying you, your company, or the application. The prefix consists of two to four unique characters (optionally followed by an underscore), and prevents your object names from conflicting with object names in the host project, or in other referenced or referencing applications on a user's machine.

To create an author prefix, use your personal or company initials. For example, author prefixes for my companies are lci_ for Leszynski Company, Inc. and kwc_ for Kwery Corporation. Before using your selected prefix, make an effort to determine if the prefix is already widely in use.

Tags for Procedures

With the large number of methods and properties listed in the Object Browser for most objects, differentiating built-in attributes of objects from those added during development can be a challenge. Procedure tags in class or form modules add a high degree of order to working with user- defined elements in the Object Browser (and other sorted lists), by clearly grouping custom procedures, methods, and properties apart from built-in object attributes.

On the other side of the coin, some developers feel strongly that procedure names should not have tags, especially in OLE Automation server applications. Before you blindly accept or condemn the use of tags in this context, try it awhile and then decide for yourself.

The LNC style prescribes the following naming convention tags for procedures:

LNC does not require or suggest assigning a data type tag to functions to reflect their return value. However, if you have a specific need to tag procedures to reflect their return value type, use the appropriate tags from the prior "Tags for Variables" section and apply them consistently to all procedures in an application.

VBA Object Name Examples

Table B.15 shows examples of VBA variables applying the various conventions for VBA objects.

Naming Conventions for Jet Objects

The data building blocks of many data-centric VB applications are Jet database objects. Creating names for database objects is no less important than creating VB application object names.

Rules for Base Names

The rules for database object base names are similar to those for VBA objects expressed earlier. Follow these rules when developing a base name for a new database object:

1. Spaces are not allowed in any object name. Where the readability of a space is required, use an underscore instead.
   
   
2. Object names begin with a letter and should include only letters, digits and underscores. Using special characters in object names is disallowed in order to comply with the naming rules of both VBA and Microsoft SQL Server. This allows your Basic variable names to include database object base names, and allows your entire schema to be easily upsized to the more powerful SQL Server platform.
   
   

   ---

   
   Rules 1 and 2 also apply to the other naming convention elements: prefixes, tags, qualifiers, and suffixes. These elements should never include spaces or special characters.
   

   ---

3. Object names use mixed upper and lower case to add readability to the name.
   
   

   ---

   
   Previously, some developers used all lower case names to allow for upsizing to Microsoft SQL Server. Starting with version 6.0, that product is now installed case-insensitive and allows you to maintain upper and lower case in object names that are moved to the server from Access.
   

   ---

4. The only non-abbreviated syntax element that can have multiple capital letters is the base name. For example, CustAddr is allowed as a base name, but not as a qualifier or suffix. However, WA is allowed for all three.
   
   
5. Object names are usually singular rather than plural. By implication, tables, queries, and forms are plural, since they usually contain more than one record, so why restate the obvious?
   
   
6. An object's base name should include the base names of any table objects it is built on, if practical. Table base names should propagate into the names of dependent objects.
   
   

You should abbreviate object base name elements wherever possible using a standardized abbreviation table such as the one in the section "Standardized Abbreviations." You can extend LNC with your own standard abbreviations as well. You should also create and use standardized terminology in your applications wherever possible. For examples, see the section "Standardized Terminology."

Base Name Length Limits

LNC includes some constraints and suggestions for object name lengths. We target our table name length at 15 characters maximum, for two reasons:

1. Short names (15 characters or less) fully display within the default column width of the Access query design grid, in case you use Access to build and maintain your Jet objects.
   
   
2. Query and form names usually include the base name(s) of the primary table object(s) they relate to, and will be unusably long if the table base names are long.
   
   

Beyond the 15 character target, we absolutely limit our table name lengths to 30 characters, which maintains compatibility with the table name length limit in SQL Server. For other objects, we target a 30 character limit as well, because the Access and VB interfaces show no more than the first 30 characters of object names in the default width of any lists or property grids.

Compound Base Names

The name of an object that is driven by a table must include the base name of the table. Thus, for the tblCust table, the primary query would be qryCust, the primary form frmCust, and so forth. Queries and forms that are sourced from multiple tables should reflect the base names of all the tables if it is practical. If not, you must decide which tables are the primary tables and list as many as possible in the name. Generally, in a multi-table query or form, the most "important" tables are not necessarily the first and second, but more often the first and last. So, a query joining tblCust to tblAddr to tblPhon to get the phone numbers for customers, would be named qryCustAddrPhon if the address information is included in the query result, or simply qryCustPhon if the address information is used to join to the phone numbers and is not displayed.

Bound control base names on forms are always equivalent to the base name of the bound field (the ControlSource). For example, a text box tied to the LastName field is named txtLastName.

Field Base Names

As a part of standardizing terminology, we adhere to the concept of a "integrated data dictionary". This principle dictates that any fields in the data structure with the same name must have the same properties and data purpose. For example, if the LastName field in tblCust is of type Text 30, and holds customer last name data, any other field named LastName in the same application must have the same type, length, properties, and purpose. If your application needs last name fields for customers and dealers, this philosophy dictates that you name them differently (such as CustLastName and DlrLastName).

Applying the integrated data dictionary principle also means that table fields do not get leading prefixes or tags, since I prefer my data dictionaries to be platform-neutral. That way, a field does not have to be renamed if data is "upsized" or ported to a platform with different data types. A table is still called a table in SQL Server, so moving tblCust there from Jet would require no table rename. However, if tblCust had a field lngCustID defined as a Long Integer in Jet, moving the database to SQL Server would require a field rename to intCustID, since SQL Server uses the data type name iInteger to mean the same as Jet's Long Integer. Since renaming fields affects all dependent objects and code, it should be avoided at all costs, so I would call the field simply CustID from the start.

Qualifiers and suffixes are acceptable in field names, however, because they describe the object's data purpose and not its type, and the purpose does not change between platforms.

Ordering Base Name Elements

Object base name elements should be ordered from left to right with respect to their importance, readability, and desired sort order. In the example from the previous section, CustLastName is a better name than LastNameCust, because the group name portion (Cust or Dlr) carries greater weight in an object's name than the specific item name (LastName or PhonNum). Think of Cust as the name of a collection of customer-related items, and this rule becomes clear—what you are really saying is that CustLastName is analogous to Cust(LastName) or Cust.LastName in Collection.Object terminology.

Some of you will naturally carry this example to its extreme and say that the Customers collection really has a Names collection with multiple elements, including Last, thus the representation of that idea as Cust.Name(Last) would lead to the field name CustNameLast instead. Such a construction model still fits within the rules of LNC, and we won't debate you against using it. In practice, however, such names often become fairly unreadable, even if they are accurate.

Tags for Jet Objects

In LNC, tags are required for Jet table and query database objects. Table B.16 lists the tags for Jet database objects.

These tags provide rich detail about the objects and sort objects with similar attributes together. For example, lookup tables and their maintenance forms are often used over and over in multiple applications. The tags tlkp, qlkp, and flkp clearly identify these objects, making it easy for you to import them from an existing database into a new one or manipulate them together in other ways. However, if a particular database does not warrant rich detail, LNC provides generic tags to use as well (for example qry instead of qsel).

The conventions prescribe a single character tag added to the front of the full object name (including the tag) of the related object in one special case shown (q[obj]). This situation occurs where a query is created solely to serve as the data source for one particular form, as in qfrmCust.

Prefixes for Database Objects

The following list describes the database object prefixes and their usage.

---

Access has its own prefix—USys—with a similar meaning. Items prefixed with USys are also not for user interaction and are not displayed in the Database window by default. In past versions of Access, it was necessary to use USys instead of zh to prevent the display of system objects in the Database window. With Access 95, you can use the zh prefix combined with setting the object's Hidden property to True to achieve this result.

---

Most of these database object prefixes use "z" as the first character. Database objects with such prefixes sort to the bottom of the Access Database window, below the user-oriented objects that are accessed more frequently.

Database Object Name Examples

Table B.17 shows examples of database objects, applying the various conventions in this section.

Creating Your Own Tags

What do you do when LNC doesn't address a particular object naming need? First, contact us and let us know why, so that we can improve the style for the benefit of all users. Second, consider if what you are trying to do is covered by the style in some other way. Suppose that your development team calls tables that link two other tables in a many-to-many relationship "linking" tables, and you want to create a new table tag tlnk as a result. However, on examination of all table tags, you would find trel already exists, defined as "Table (many-to-many relation)", which is the correct tag for what you need. Even though the nomenclature is not exactly what you might use, it is better to use an existing tag than create another one.

Finally, when other options are exhausted, you can create a custom tag to address your need. When creating a custom tag, these should be your guidelines:

1. Do not redefine an existing tag. No matter how badly you really want the three or four character combination for your own purpose, never re-use a defined tag.
   
   
2. Do not change the rule for tags. Stay within the three to four character range followed by LNC.
   
   
3. Use the conventions in existing tags as your guide for the new one. For example, all table tags start with t, all query tags with q, and so forth. Any new tags you make for these objects should begin with the pre-defined letter. See Table B.18 below for guidelines on standard tag components; note that some of the examples are from the Office version of LNC. Tag components that can be easily inferred from the tags in this document are not listed in the table (for example, the component fox for FoxPro can be inferred from the tags tfox and dfox.)
   
   

When creating a new tag, it should be mnemonic enough to uniquely shorten the word it represents, and should only use characters from the root word or a generally accepted shorthand.

To create tags for object variables pointing to OLE Automation server applications, start with a three character application prefix that is unique and applicable. Add to the application abbreviation a three-character tag for the entry point of the application, such as bas for "Basic" in "Word.Basic".

For example, to create a tag for OLE Automation with Shapeware's Visio program, which is an OLE server, use either vsd (the data file extension) or vis (a mnemonic for Visio) as the basis for the tag. Next, add app for Application, because the entry point to Visio's automation engine is a call to "Visio.Application". Thus, the tag and it's use in variable declarations would look like this:

Dim ovisapp As Object



Dim ovisappDoc As Object



Set ovisapp = CreateObject("Visio.Application")



Set ovisappDoc = ovisapp.Documents.Open("C:\VISIO\HOUSE.VSD")

VBA Coding Conventions

In addition to object naming conventions, LNC suggests several standardized coding conventions for VBA procedures.

Common Practices

Common coding practices in VB coding that are supported by LNC include:

• Use indents of two characters to show nesting program structures (I find the default of four spaces produces too much white space and too many truncated code lines).
  
  
• Use Option Explicit in each module to force declaration of variables before use.
  
  
• Declare all necessary variables at the top of each procedure.
  
  
• Place comments and error handling in each procedure.
  
  

Code Comments

There are as many in-line Basic code commenting styles as there are Basic coders. Whatever convention you use, the keys are to be terse yet descriptive, and to be consistent.

LNC suggests placing the following minimum set of comments at the beginning of each procedure:

In addition, I personally sometimes use these sections in the heading of a procedure:

Some developers like to keep a change log as comments noting all revisions in a procedure. I suggest keeping such comments at the bottom rather than the top, since they are less frequently accessed than the code they displace.

Comments placed on the same line as code should be separated from the code by at least two spaces. Comments placed on their own line should be no longer than 60 characters so they are displayed in full in the default module design view size.

Trapping Errors

Every procedure that can fail—which is virtually every procedure with more than a few simple lines—should have an error trap. Error traps are created by placing this line at the beginning of the procedure, after the header comments and before any other statements:

On Error GoTo procname_Err

The marker procname should be replaced with the full procedure name. The error handler is placed at the bottom of the procedure, denoted with the label procname_Err:. At the end of the error handler, control is returned somewhere in the procedure, usually to a line label name procname_Exit that precedes a block of code immediately above the error handler.

To allow you to turn off error trapping during program debugging, LNC suggests that you place the On Error statement inside a conditional compilation directive, like this:

#If pcccDebug Then



  On Error GoTto 0



#Else



  On Error GoTto procname_Err



#End If

Before running an application, you can enable or disable error trapping by setting the value of pcccDebug to -1 (True) or 0 (False) in the "Conditional Compilation Arguments" text box on the Module tab of the Options dialog.

We use the procname_label structure rather than the label_procname structure preferred by many coders in order to maintain our ObjectVerb construction metaphor as described. Some developers prefer to place the qualifier of the label first, as in Err_procname, but philosophically the phrases Err_, Exit_, and so forth are not class tags, they are qualifiers for the line label object, thus they belong at the end like any other qualifier. This argument becomes more compelling when you remember that you can also create line labels for GoSub and GoTo statements in VBA, and thus creating many different combinations of leading characters, as if they were tags, becomes problematic.

Standardized Abbreviations

Table B.19This section lists some of our standard abbreviations we use when building object names.

Standardized Terminology

When creating code comments, object names, help files, and system documentation, it is important to use terms that have an accepted and non-ambiguous meaning. You should build a list of standardized terms for your specific industry or application to ensure consistency. Table B.20 provides a short sample list of standardized terminology. These terms are not a feature of LNC, they are only examples as a starting point for your efforts.

How to Get the Leszynsiki Naming ConventionsLNC

You can get copies of this document from Kwery Corporation. The following additional information is also available: the Leszynski Naming Conventions for Microsoft Solution Developers document, the Leszynski Naming Conventions for Microsoft Access document, Windows Help file versions of each LNC document, and LNC programmers' tools. Contact Kwery via the order line at 1-800-ATKWERY, or on the product information line at 206-644-7830. Kwery can also be reached by CompuServe and fax at the numbers that follow.

Sending in Your Feedback

We welcome your feedback on these conventions, including your likes, dislikes, stories, and suggestions. You may also submit new tags for consideration. Please communicate with Kwery via CompuServe at 71573,3261 or by fax to 206-644-8409.

The Fine Print

This document is provided as is, without warranty of any kind, either express or implied, including but not limited to implied warranties of quality, performance, merchantability, or fitness for any particular purpose.

Some naming convention elements in this document are from the L/R white paper Naming Conventions for Microsoft Access—The Leszynski/Reddick Guidelines for Access 1.x, 2.x, Copyright c 1994 Stan Leszynski and Greg Reddick. For a comparison of L/R and LNC, see the document Leszynski Naming Conventions for Microsoft Access.

386MAX, Btrieve, Lotus 1-2-3, Microrim, Microsoft, Microsoft Access, Microsoft Excel, Microsoft Office, Microsoft PowerPoint, Microsoft Project, Microsoft Schedule Plus, Microsoft SQL Server, Microsoft Visual Basic, Microsoft Visual C++, Microsoft Visual FoxPro, Microsoft Windows, Microsoft Word, Paradox, R:BASE, Qualitas, and Visual Basic for Applications are trademarks or registered trademarks of their respective owners.

Kwery Document Version Number: 95.1.1.