Code Quality - Naming Conventions :
Steve McConnell, Code Complete, The Power of Variable Names :
I. Most Important Naming Consideration :
The most important consideration in naming a variable is that the name fully and accurately describe the entity the variable represents. An effective technique for com- ing up with a good name is to state in words what the variable represents. Often that statement itself is the best variable name. It’s easy to read because it doesn’t contain cryptic abbreviations, and it’s unambiguous. Because it’s a full description of the entity, it won’t be confused with something else. And it’s easy to remember because the name is similar to the concept. Names should be as specific as possible. Names like x, temp, and i that are general enough to be used for more than one purpose are not as informative as they could be and are usually bad names.
A good mnemonic name generally speaks to the problem rather than the solution. A good name tends to express the what more than the how. In general, if a name refers to some aspect of computing rather than to the problem, it’s a how rather than a what. Avoid such a name in favor of a name that refers to the problem itself.
Names that are too short don’t convey enough meaning. The problem with names like x1 and x2 is that even if you can discover what x is, you won’t know anything about the relationship between x1 and x2. Names that are too long are hard to type and can obscure the visual structure of a program.
II. Kinds of Names to Avoid :
- Avoid misleading names or abbreviations Make sure that a name is unambiguous. For example, FALSE is usually the opposite of TRUE and would be a bad abbreviation for “Fig and Almond Season.”
- Avoid names with similar meanings Avoid variables with different meanings but similar names
- Avoid names that sound similar, such as wrap and rap
- Avoid numerals in names (file1, file2,…)
- Don’t differentiate variable names solely by capitalization
- Avoid the names of standard types, variables, and routines
- Don’t use names that are totally unrelated to what the variables represent
- Avoid names containing hard-to-read characters