|
Naming rules make programs more understandable by making them easier to read. They
can also give information about the function of the identifier, for example, whether
it's a constant, package, or class, which can be helpful in understanding the code.
Perhaps one of the most influential aids to understanding the logical flow of an
application is how the various elements of the application are named. A name should
tell "what" rather than "how." By avoiding names that expose the underlying implementation,
which can change, you preserve a layer of abstraction that simplifies the complexity.
For example, you could use GetNextOrder()
instead of
GetNextArrayElement().
A tenet of naming is that difficulty in selecting a proper name may indicate hat
you need to further analyze or define the purpose of an item. Make names long enough
to be meaningful but short enough to avoid being wordy. Programmatically, a unique
name serves only to differentiate one item from another. Expressive names function
as an aid to the human reader; therefore, it
makes sense to provide a name that the human reader can comprehend. However, be
certain that the names chosen are in compliance with the applicable rules and standards.
Following are recommended naming techniques:
Methods
•
Names of methods should contain active verb forms and imperatives (DeleteOrder,
OpenSocket).
It is not necessary to include the noun name when the active verb refers
directly to the containing class. Example:
Socket.OpenSocket(); // AVOID! No need to mention “Socket” in name
Socket.Open(); // PREFER
•
Avoid elusive names that are open to subjective interpretation, such as
Analyze()
for a routine, or xxK8 for a variable. Such names contribute to ambiguity
more than abstraction.
•
Use the verb-noun method for naming routines that perform some operation on a given
object,
such as
CalculateInvoiceTotal().
•
In method overloading, all overloads should perform a similar function.
Variables
•
Do not use any special prefix characters to indicate that the variable is scoped
to the class, as in _name or
m_name.
Always use the “this” keyword when referring to members at a class’s root scope
from within a lower level scope, as in this.name.
•
Do not use Hungarian notation for field names. Good names describe semantics, not
type.
•
Prepend computation qualifiers (avg, sum, min, max, index) to the beginning of a
variable name where appropriate.
•
Use customary opposite pairs in variable names, such as min/max, begin/end, and
open/close.
•
In object-oriented languages, it is redundant to include class names in the name
of class properties, such as Book.BookTitle. Instead, use
Book.Title.
•
Collections should be named as the plural form of the singular objects that the
collection contains. A collection of Book objects is named Books.
•
Boolean variable names should contain “Is” or “is” which implies Yes/No or True/False
values, such as
isFound,
or
isSuccess.
•
Avoid using terms such as Flag when naming status variables, which differ
from Boolean variables in that they may have more than two possible values. Instead
of
orderFlag,
use a more descriptive name such as orderStatus.
•
Even for a short-lived variable that may appear in only a few lines of code, still
use a meaningful name. Use single-letter variable names, such as
i
or
j
for short-loop indexes only.
•
Constants should not be all uppercase
with underscores between words,
such as
NUM_DAYS_IN_WEEK.
Constants follow the same naming rules as properties. The aforementioned constant
would be named
NumDaysInWeek.
•
Temporary variables should always be used for one purpose only; otherwise, several
variables should be declared.
Parameters
•
Do not prefix method parameters with any special character to indicate that they
are parameters.
•
Parameter names should follow the naming rules for variables (above).
Tables
•
When naming tables, express the name in the singular form. For example, use
Employee
instead of
Employees.
•
When naming columns of tables, do not repeat the table name; for example, avoid
having a field called EmployeeLastName in a table called
Employee.
•
Do not incorporate the data type in the name of a column. This will reduce the amount
of work needed should it become necessary to change the data type later.
Microsoft SQL Server
•
Do not prefix stored procedures with sp_, because this prefix is reserved for identifying
system-stored procedures.
•
In Transact-SQL, do not prefix variables with @@, which should be
reserved for truly global variables such as @@IDENTITY.
General
•
Implementation details, in particular type specifications, should not be mention
in the name of a descriptor. This is a common trait in procedural languages like
Visual Basic where lowercase prefixes are used to encode the data type in the name
of the identifier,
such as
•
Invoice.
This approach is not applicable to contemporary languages where the aforementioned
identifier is written simply as invoice.
•
Names with semantic content are preferred to names with type specifications (sizeOfArray
instead of
anInteger).
•
Names of descriptors should be chosen in such a way that they can be read like a
sentence within instructions.
•
Minimize the use of abbreviations. If abbreviations are used, be consistent in their
use. An abbreviation should have only one meaning and likewise, each abbreviated
word should have only one abbreviation. For example, if using min
to abbreviate
minimum,
do so everywhere and do not later use it to abbreviate
minute.
•
When naming methods, include a description of the value being returned, such as
GetCurrentCustomerName().
•
File and folder names, like method names, should accurately describe what purpose
they serve.
•
Avoid homonyms when naming elements to prevent confusion during code reviews, such
as
write
and
right.
•
When naming elements, be aware of commonly misspelled words. Also, be aware of differences
that exist between American and British English,
such as
color/colour and
check/cheque.
|