The Natural Language Naming Convention
Modules are collections of subprograms and their supporting objects. Although the names of modules are ignored in many environments (VB 3.0, for example), they should still be chosen carefully because they reflect and determine the organization of the software.
If the object is a name that will be directly referred to in any operation, append "_Code", "_Module", or similar text to the name of the underlying object to prevent confusion.
If you have chosen an object-based method of organization, the names of modules should be nouns or noun phrases. If you have chosen a functional method of organization, the name should reflect the common nature of the functions and procedures contained.
Functional organization is often the simpler method when a project is very small, but it rapidly gets confusing when the project grows. For this reason, it is usually better to start with an object-based method of organization right from the start. Changing the names and organization of the code is a relatively simple process in languages where the module names are not significant (to the compiler), but re-organization is otherwise a fair amount of work. This is particularly true when the search and replace feature of the language cannot reach all of the places from which the function might be called (as in object events in Microsoft Access).
A function is a subprogram that returns a value. A function name should begin with an article (a, an, or the). A function name should clearly indicate the purpose of the function and the nature of the return value.
Functions should be the most carefully chosen names in any application. An ideal function name clearly describes the purpose of the function and implies the return value. When convenient, the function name should also convey the number, nature, and order of all parameters, but this should be dispensed with when doing so muddies the purpose of the function.
If the principle of functional cohesion is rigidly adhered to, the names of the functions are simple and obvious. That is, a function that performs a single operation is easy to name, but a function that does many things is more difficult to identify.
When naming a function, consider how it will be used. Most often, functions are called on the right-hand sign of an assignment statement.
My_Variable = The_Result_of_this_Operation()
A Boolean function, however, asks a simple question with a true/false answer. Always keep in mind that the most common place to call a Boolean function is between If and Then.
If Add_Item_to_List(New_Item) Then
A procedure is a subprogram that does not return a value. A subprogram name should form a complete declarative sentence that accurately describes the effect of the procedure when the procedure name is coupled with its actual parameters.
Insert_A_Column_Named Column_Name, In_Column_Position
Parameters are the names of the external objects that the subroutine needs to work with, for, or on. A subprogram can either use an entity because the object is globally or modularly visible, because the entity is passed to the subprogram, or because the subprogram creates the entity.
Parameters are a safer means of information transfer than any variety of shared variables.
Actual parameters are the values actually passed to the functions and procedures. The values commonly take the form of literals, variables, or constants. Some languages also allow functions to be passed as variables. That is, the language allows the programmer to eliminate the step of assigning the value to a variable.
The name of the actual variable should be chosen for its readability in the context of the subroutine call that uses the variable.
Dim Column_Name As String
Dim In_Column_Position As Integer
'Collect name and new column position.
Insert_A_Column_Named Column_Name, In_Column_Position
Formal parameters are the names given to the parameters in the declaration of the function or procedure. Formal parameters are used to internally refer to information that is passed to the subroutine when it is called.
Use nouns modified by prepositional phrases to name your formal parameters. This noun/prepositional phrase should clearly indicate the type of the parameter expected. When possible and convenient, select a name that indicates the purpose for which the parameter will be used. For example:
Spreadsheet_to_Modify
Number_to_Square
Record_to_Modify
The names of all variables shall clearly describe of the contents, scope, and type of the variable.
The Scope and Visibility of a variable shall be reflected in the names of all variables except local variables.
A global variable is a confession that you were too lazy or too stupid to figure out the right way to do the job. Thus, global variables should look as ugly and awkward as possible. Reverse Proper Name format is easy to type (use the caps lock key) and ugly enough so that it stands right out.
If you have to use a global variable, make sure they are easy to find and repair (eliminate).
mY_uGLY_gLOBAL_vARIABLE
Module variables are in scope for and visible to all of the procedures and functions in the module. The names of module-wide variables shall start or end with descriptive text like "Shared_" and shall be clearly descriptive of the contents and type of the variable.
Shared_User_ID
Shared_Form_Caption
Form_Cancel_Shared
Local variables are the easiest programming entities because they are usually very specific. They also tend to be the entities that most programmers name with little or no thought.
Never use variable names like "a" ,"b" ,"ii", etc. Even in an extremely simple subroutine, some interpretation (no matter how automatic to the trained professional) will always be required. Note that there are many situations where simply selecting good variable names would eliminate the need for several lines of comments.
The importance of selecting good names for local variables increases proportionally to the size of the subroutine. This does not mean that you should ever choose variable names carelessly; it just means that you will be punished less for carelessness when the scope is small.
Languages (most of them) that permit untyped variables frequently provide constructs and methods that depend on the use of untyped variables. You may not be able to avoid this kind of variable even if you feel (as we do) that the use of such a tool is inherently sloppy.
Numeric variables should reflect the type of number that the variable will contain and the purpose that the variable will be used for.
Dim Record_Number As Long
Dim Interest_Rate As Double
Dim Student_ID_Number As Long
Dim Grade_Point_Average As Single
The name of a string variable shall clearly indicate the text nature of the contents and shall clearly indicate the purpose of the variable.
Dim Last_Name As String
Dim Full_URL As String
Dim Form_Caption As String
The name of a Boolean variable will be in the form of a positive assertion.
Dim Linking_Records_are_Updated As Boolean
Dim Transaction_was_Completed As Boolean
Dim Action_was_Cancelled As Boolean
Loop indexes, more correctly called loop invariants, should have names that end in the string "_Index" (for processing arrays), the string "_Item" (for processing collections), or a similar string indicating the nature of the object being processed.
Record_Array_Index
Form_Item
ModelTerm_Item
User-Defined Types should have names that end in the string "_Type". Names of internal fields will follow the same rules as local variables.
Note that user-defined types should not contain variable-length string fields. Unless a user-defined type is explicitly required (as by a DLL), a class will solve the problem more reliably and reusably.
Private Type RecordChoice_Type
Record_Number As Long
Record_Is_Selected As Boolean
End Type
Variables that represent the vast array of data access objects should clearly represent the identity and type of the object.
Chosen_Snapshot
People_Table
Update_Recordset
Use the ALL CAPS format to distinguish constants from those provided by Microsoft. If the constants are global, append the string "_GLOBAL" to the end of the name.
When naming constants, take care to avoid names that might be confused with SQL keywords. SQL keywords share the format and may share general context. For example, do not create a DISTINCTROW constant.
const APPLICATION_NAME = "WebTracker"
Classes and their properties are distinguished from other names in this convention by lack of underscores. Proprietary prefixes may be used for classes that will be exported outside of your project.
Classes, added to VB in version 4.0, provide a robust, reusable alternative to private types and arrays. In addition, the ability to explicitly define and control all of the operations on the class and its members within the envelope of the class module encourages design elements that make programs shorter, simpler, and easier to change without introducing new errors.
Classes themselves are templates. Use the general guidelines for variables when declaring an instance of a class.
Class Name: ModelTerm
Loop Invariant Name: ModelTerm_Item
Local Variable: This_ModelTerm
Standard classes (all EXCEPT collection classes) should be named with a singular noun with one or more leading modifiers.
ModelTerm
GridSearchParameterFile
FactorSliceLevel
Collection classes should be named with a plural noun with one or more leading modifiers.
ModelTerms
SphericalConstraints
TemporaryEmployeeRecords
Properties may have simple or compound names. Do not use underscores when compound names are used.
Note that there is no need to make property names unique between classes since properties can only be used in their fully qualified form, i.e. using the full dot notation.