Naming and Formatting Conventions for Visual C++ Objects and Variables
This book's Introduction lists the Hungarian Notation prefixes that are most commonly used. This appendix expands on prefixes and covers the formatting of code, which can help you write better applications.
These naming conventions use a modified form of Hungarian Notation that commonly is used in C and C++ programming. The term Hungarian comes from the nationality of the conventions' inventor, Charles Simonyi, who at one time worked on the development of Access 1.0 at Microsoft. The prefix sz, which defines a zero-terminated string variable in C, is a common letter combination in the Hungarian language.
You might wonder why you should follow these rules when naming your variables. The long and short of it is that when we all follow the same set of rules, it's much easier to interact with each other. Of course, no variable name, no matter how well formed, will make poorly written code good. But well written and well formatted code, with variable names that follow standards, is much easier to debug and maintain.
NOTE
It's a good idea to learn and use as many of the established standards as you can. When you're thinking about making a career change, the ability to show well-written code that conforms to standards will generally be a positive influence on prospective employers.
Hungarian Notation for Variables and Objects
There are a number of simple rules that you should follow when naming your variables and objects. The following is a set of rules that will assist you in making your code as readable as possible.
NOTE
Microsoft doesn't always follow these guidelines. The file DBDAOERR.H has #defined variables that are mixed case, and other Windows header files demonstrate the same use of mixed case.
For defined identifiers created using the #define directive, use all capital letters. Use underscores to break the name into logical words as necessary. For example, the NULL symbol is defined as follows:
#define NULL ((void *)0)
Notice that the name NULL is in capitals. Also notice that NULL is defined as an address, not a scalar variable.
NOTE
Remember that NULL (as used in C/C++) is different from null as used by databases. NULL in C/C++ is used to indicate an address that is undefined. The database null indicates a field that has no value, which is different from a field that contains a string of zero characters. A character field of zero characters isn't a null field.
For all other identifiers, use mixed-case names. Don't use underscores as part of a regular name. For example:
Correct
Incorrect
FirstName
FIRSTNAME
firstname
Firstname
first_name
For class definitions, use a preceding capital C, as in COurClass. This helps identify the item as a class definition.
For member variables in a class, precede the name with an m_. For example, use m_szFirstName as the name of a variable that holds a first name. The m_ prefix tells you (and anyone else reading your code) that this is a member variable.
Use Hungarian Notation for all simple variables. For variables that are classes, structures, or unions, don't use a prefix.
It's permissible to use single-character variables for short loop counters, but for no other purpose. If a loop is more than a few lines long, use a significant name for the loop counter. Most loop counters are the characters i, j, and k, used in that order.
Table B.1 lists the more commonly used prefixes of Hungarian Notation. Nothing in the concept of using prefixes prevents you from creating your own prefixes for types that don't already have a prefix defined. However, resist the urge to change a prefix of a data type that already has a prefix defined.
Table B.1. Hungarian Notation prefixes.
Prefix
Description
b
BOOL (int)
by
BYTE (unsigned char)
c
char
cx, cy
short (used as x or y length; the c stands for "count")
dw
DWORD (unsigned long)
fn
Function (not used often)
h
Handle (generic)
i
int
l
LONG (long)
n
short or int
p
Pointer
s
String
sz
A string terminated by the 0 byte
w
UINT (unsigned int) or WORD (unsigned word)
x, y
short (used as an x-coordinate or y-coordinate)
Formatting Your C/C++ Source Code
When writing C or C++ code, you should try to make your source as attractive as possible.
Don't comment the obvious. The comment in the following statement is meaningless, because the statement's action is clear without it:
++i; // Increment i
Align your code so that opening and closing French braces are in the same column and on lines by themselves. Don't place an opening brace at the end of a statement that begins a block. The following example shows how you can easily see the beginning of the block, even if the indentation isn't always correct. When braces are on lines by themselves (with comments, if necessary), they're easier to see:
for (i = 0; i < 5; I++)
{// Document the loop's purpose!
j = nIndexArray[i];
// Other statements....
}
Place variable declarations at the beginning of a module whenever possible. Don't put more than one declaration on a line, and always initialize variables:
// Indent all source lines after declarations by one tab stop
for (i = 0; i < ARRAY_SIZE; I++)
{
dTotal += dParameter[i];
}
dAverage = dTotal / ARRAY_SIZE;
return (dAverage);
}
Use spaces logically. Separate symbols (such as =, +, -, *, and /), constants, variable names, and keywords with both leading and trailing spaces:
// Hard to read:
i=(j/25)+45/2*8;
// Easier to read:
i = (j / 25) + 45 / 2 * 8;
When in doubt (for many programmers, this is most of the time), use parentheses in expressions. The following examples show how hard it can be to quickly see the order of expression execution when there are no parentheses:
// Hard to read and understand:
i = j / 25 + 45 / k * 8;
// Easy to read and understand:
i = ((j / 25) + (45 / k)) * 8;
Notice in the second example that the programmer didn't want the default order of execution!
Format your code logically. Don't have more than one executable statement per line of source code. Doing this makes it difficult to follow the flow of the program and impossible to set a breakpoint somewhere other than at the first executable statement on the source line.
Indent, indent, indent. Never skip indentations. Whenever you do, you will usually induce a program logic error (this is Murphy's Law).