Naming Conventions
Variable Naming
Variable names have the following
structure:
<scope><constructor><type><qualifier>
Section
|
Description
|
Example
|
|
<scope>
|
Optional. Indicates the scope and/or usage of the
variable (eg. Global, Module, Static, Ref, Val)
|
g_arrstrStateName
|
|
<constructor>
|
Optional. Base-type modifier
|
arrsStateName
|
|
<type>
|
Required. Indicates the base-type of the variable
(eg. integer, string, double etc.)
|
lStateidFirst
|
|
<body>
|
Required. Describes the variable
|
arrsStateName
|
|
<qualifier>
|
Optional. Denotes a derivative of the
variable
|
sStateNameTmp
|
Do not use the optional Visual Basic
variable suffixes ($, %, & etc.).
Scope Prefix <scope>
The
following table defines the standard scope and usage prefixes. Scope prefixes (g_, m_, s_) should be used
for all variables not local to a function.
Usage prefixes (r_, v_) should be used for all function parameters. Define all variables at the top of their
enclosing scope blocks.
|
Prefix
|
Description
|
|
g_
|
Global
|
|
m_
|
Local to module or form
|
|
s_
|
Static variable
|
|
v_
|
Variable passed by value (local to a
routine)
|
|
r_
|
Variable passed by reference (local to a
routine)
|
ü Variables should always be defined with the smallest scope
possible. VB global variables should be
avoided whenever possible, use a class (globals.cls) to contain these variable
(VB does not properly release global memory on object destruction).
ü
Always
explicitly declare the calling semantics of variables as ByRef or ByValue. Use the r_ and v_ prefixes to further
reinforce their usage.
ü
Only
use ByRef if you really intend to modify the parameter or to reduce copy
overhead when passing string variables.
Constructor <constructor>
The Constructor is used to optionally
modify the base type. The following
tables define the standard constructors to use for VB and C++.
|
Constructor
(VB)
|
Prefix
|
|
Array
|
arr
|
Constructor
(C++)
|
Prefix
|
|
Pointer
|
p
|
|
Array (range)
|
rg
|
|
Mapping
|
mp
|
A full list of recommended C++ naming
constructors is given in the Hungarian Notation Reference in Appendix 1.
Type Prefix <type>
The following tables define variable name
prefixes for use in VB and VBscript code. These prefixes should be used with all
variable and function names:
|
Data Type
(VB)
|
Prefix
|
Alternative
Notation
|
|
Array
|
a
|
arr
|
|
Boolean
|
b
|
bln
|
|
Double
|
d
|
dbl
|
|
Date
|
dte
|
|
|
Error
|
err
|
|
|
Single/Float
|
f
|
flt
|
|
Long
|
l
|
lng
|
|
String
|
s
|
str
|
|
Object
|
o
|
obj
|
Do not use the Visual Basic
“Currency”, “Integer” or “Variant” data types.
ü “Variant” usage is permitted only for ByRef parameters to/from
VBScript.
A full list of recommended C++ type
prefixes is given in the Hungarian Notation Reference in Appendix 1.
Body <body>
The body of a variable or routine name
should use mixed case and should be as long as necessary to describe its
purpose. In addition, function names should begin with a verb, such as blnInitNameArray, intGetUserPref or blnSetUserPref.
For frequently used or long terms, use
standard abbreviations to help keep name lengths reasonable. In general, keep
variable names to 32 characters or less.
When using abbreviations, make sure they are consistent throughout the
entire application. Use the singular
form of nouns in preference to the plural, even when describing variables
containing multiple values (eg. Use g_arrstrStateName
or g_asStateName, not g_arrstrStateNames).
Qualifiers
Related variables are often used to manage
and manipulate a common object. In these cases, use standard qualifiers to
label the derived variables. The
following table defines common qualifiers and their standard meaning:
Qualifier
|
Description
|
|
First
|
First element of a set.
|
|
Last
|
Last element of a set.
|
Next
|
Next element in a set.
|
|
Prev
|
Previous element in a set.
|
|
Cur
|
Current element in a set.
|
|
Min
|
Minimum value in a set.
|
|
Max
|
Maximum value in a set.
|
|
Save
|
Used to preserve another variable that
must be reset later.
|
|
Tmp
|
A "scratch" variable whose
scope is highly localized within the code. The value of a Tmp variable is usually only valid
across a set of contiguous statements within a single procedure.
|
|
Src
|
Source. Frequently used in comparison and
transfer routines.
|
|
Dst
|
Destination. Often used in conjunction
with Source.
|
User Defined Types
Declare user defined types in all caps with
_TYPE appended to the end of the symbol name. For example:
Type CUSTOMER_TYPE
sName As String
sState As String
lID as Long
End Type
sName As String
sState As String
lID as Long
End Type
When declaring an instance variable of a
user defined type, add your own prefix to the variable name to reference the
type. For example:
Dim custNew as CUSTOMER_TYPE
Choose Type Prefixes carefully and use them
consistently. Acronyms or abbreviations
are preferred over English words, to avoid confusion with <body> names.
Function and Procedure
Naming
Follow the same rules as Variable naming
with the following additions:
ü If the function is a true function (it returns a value with no
side-effects), splice the word From at an appropriate place in the <body> section.
Examples
Function strStateNameFromStateID (ByVal
v_lngStateID as Long)
sStateNameFromStateID = g_dctStateNameFromStateID (v_lngStateID)
End Function
sStateNameFromStateID = g_dctStateNameFromStateID (v_lngStateID)
End Function
Constant, Macro, and
Enumeration Naming
Follow the same rules as Variable naming
with the following exceptions:
Constants & Macros
ü To aid readability, the <body> and <qualifier> sections of Constant and Macro names should be UPPER_CASE with
underscores (_) between sections and words.
Enumerations
ü These should follow a <class
abbrev><body> format using mixed case
only or be consistent with constant and macro naming conventions.
ü <class abbrev> should be a shortened
acronym for the owning class module (i.e. for Authenticator, the abbreviation
would be Auth or AUTH).
ü Enumeration identifiers should end with the word ‘Enum’.
ü Scope, constructor, type, and qualifiers are not necessary.
ü Individual elements may have implicit or explicit values.
Examples
m_lRESUME_ID_MAX ' Max ResumeID for Resume set. Long value.
Local to module.
g_sNEW_LINE ' New Line character string. Global to entire application.
g_sNEW_LINE ' New Line character string. Global to entire application.
AuthUserId ‘ Implied value 0
AuthIssueTime = 2& ‘ Explicit value
…
End Enum
- or -
Public Enum
AUTH_TICKET_ARRAY_INDEXES_ENUM
AUTH_USERID
AUTH_ISSUE_TIME = 2&
…
End Enum
Program and Component Naming
The names of all
programs and components begin with the 3-letter upper-case abbreviation MNS (Monster).
The next letter is
lower-cased and drawn from the following:
- s - Business Service.
- o - General Object Class. Contains utility methods that do not
warrant being a Business Service because they contain no business rules. Typically this will be used to provide
base core services wrap interaction with a vendor-supplied class to
provide a level of indirection.
This can aid in switching vendors if done well. Attempt to not let any vendor classes
propagate into the signatures of methods in this class for maximum
portability. Try to avoid naming
everything an 'o' class; this can be tempting.
- i
- a - Runnable Application.
- t
Under no circumstances is
existing code to be duplicated to expedite delivery of any product. This is critically important for ongoing
maintenance efforts and bug isolation.
In almost every case, the copy of the original code never receives
important updates and may continue to expose buggy or outdated business logic.
This will be strictly
enforced by the Architecture group!
Each file, regardless of language, should
have a header section with the following information:
ü File Name.
ü Purpose – what the program does, not how it does it.
ü External dependencies – databases, servers, software components.
ü Summary of performance testing results and known bottlenecks.
ü Descriptions of known problems and how/when they might occur.
ü List of all raised errors.
This information should be included for the
current version only. Revision histories
and modified-by information should be excluded, as the source control system
will contain this information.
ü Always use “Option Explicit” for VB and VBScript code
Formatting
- Indent blocks of code according to syntactic scope.
- Use blank line spacing around logical blocks of code.
Comments
Post a Comment