Whitepaper: Improving Software Development Productivity

Standards for naming variables are inconsistent. Not only are they inconsistent for the industry, but they are often inconsistant inside of a single corporation, or even inside of a single department or team. This can pose a significant problem; without consistency, it's harder to recognize just what a variable name means, and that means lower productivity and more bugs. That's bad for everyone, both programmers and users alike.

Worse yet, opinions vary widely about what such the standard should be; in some places, Hungarian Notation is very common, but different groups use different abbreviations. In other cultures, however, Hungarian Notation isn't used, since, some say, there is a lack of opacity and a tendency to violate Object Oriented principles. Standards vary wildly in many other areas; such as whether to indicate scope in variable names, word separators, and so forth.

It's very important, whether you are a large team, small team, or an individual, to carefully set variable naming conventions. Without them, you can be awash in a sea of conflicting variable names, forever unsure of whether it's book_index or intBookIndex.

Guidelines

This is fittingly the first guideline to be presented, as it is also the most important. Variable names must, without exception, indicate the function of that variable. This allows a programmer – either the original author, or a later maintenance programmer – to easily comprehend the purpose of a variable. Without that ability, it can take a programmer far longer to decipher the purpose of a section of code; even worse, if the variable name is incorrect, it may in fact lead the programmer to believe that a section of code performs a function other than it's actual function.

Variable names should never be generic, e.g. variables i, j, and k for loop counters, names such as temp, tmp, foo, and bar for temporary variables, etc. If a variable cannot be clearly named, then it is suggested that a variable does not have a clear purpose. If it does not have a clear purpose, than time would be well spent refactoring the code so that the purpose of a variable is clear, and thus it can be clearly and specifically named.

Variable names should not be reused within the same scope; they should not be reused within different scopes unless the difference is clear. For example, it is likely unwise to create a variable within the scope of a routine that has the same name, or a very similar name, as that of a global variable.

Note that it is very common for variables to change function slightly over time. If this happens, it is wise to change the name of the variable so as to maintain accuracy. With the prevalence of “Find and Replace” facilities in modern editors, it is often trivial to change the name in all it's occurrences, and virtually always worth the time.

Readability is very important. If variable names are difficult to read, then it can significantly hurt understanding of the code. The details of the scheme are not important; it is important, however, to adopt a scheme that is consistent. If it is not consistent, then the scheme becomes just that much more confusion, rather than a aid to understanding.

When adopting a capitalization/formatting scheme, the following factors should be considered:

• What is the usual scheme for the language/environment? What does the vendor documentation use?

  For example, it is common for Microsoft .NET-based code to use a standard with variables namedLikeThis, whereas in the Unix/Linux environments it is more common to see names_like_this.

• Does the scheme effectively separate words?

  It can be confusing, for example, to type settextextended, not to mention confusing to read. setTextExtended, SetTextExtended or set_text_extended are far easier to read.

• Is it easy to read?

Abbreviations can be very dangerous. If not used carefully, then they can be very difficult to decipher. Programmers should keep in mind that while they only have to write a piece of code once, they will very likely have to read it many times; thus, it is wise to use a longer but more readable name versus a shorter name with a difficult to remember acronym or abbreviation.

If used, either for the sake of consistency or else because a variable name would otherwise be of an excessive length, they should be consistent. If a concept is not consistently abbreviated, then it can be difficult to decipher the correct name for a given instance; further, it can lead to multiple variables with very similar names. If a the page counter is sometime referred to as Page_Counter, PgCntr, PageCntr, or PageCtr then a future maintenance programmer may have a very difficult time remembering which abbreviation is used for any given variable name.

Case should not be used to differentiate between variables.

Some languages have case sensitive variable names, so Foo is different from foo. This is dangerous; don't rely on Foo and foo being different. At best, it's confusing.