CSC/ECE 517 Summer 2008/wiki2 2 rapodraz
Variable Naming in Programming
Almost all programming languages allow the programmer a great deal of freedom when naming variables in a program's source code. It may seem like this is an obvious advantage, as it gives the programmer a great deal of flexibility. However, this level of freedom may incorrectly reflect the notion that variable naming is unimportant. Since variable identifiers can be named in many different ways, they often are, and the result is a high degree of inconsistency that can be problematic for code readability and maintenance.
Naming Conventions
In most contexts, the term "naming conventions" refers to a set of rules used to name variables depending on its scope, type, etc. Naming conventions are a form of metadata. A good set of naming conventions can be very useful and is often part of good programming practice. Naming conventions may differ among programming languages and projects, but the purpose is the same: to provide information about the variable identifier in the name itself. Some examples of common naming conventions include:
- Using lowercase for a single word name
- Using capitalization or underscores to separate multi-word names
- Using all caps for constants
- Using variable prefixes to indicate scope or type
Examples of good, well known naming conventions are Hungarian Notation, and the Symbian OS naming conventions. There are other aspects of naming which may not be specific to a particular naming convention, but are part of general good practice, such a name's length and the use of abbreviations. It is generally preferred to use short names and abbreviations when possible without confusing the meaning of the name. Common examples are using "ptr" for "pointer" or "ctr" for "counter." Be careful when abbreviating, however, and consider whether removing vowels from a word or simply truncating the word is more effective. For example, for a word like "customer," "cust" may be a better abbreviation than "cstmr."
Often variable names include a verb, and in this case it is always best to use the active voice. For example, never use a name like "recieverForMessages" when "messageReciever" would work. It would even be possible to abbreviate this to "msgReceiver" to be even more concise. As another example, don't use "countOfItems" when you can use "itemCount." Never use negative forms of a word for variable names, such as state. Otherwise you may run into confusing double-negative boolean expressions in code.
Be careful that your variable name is not the same as a reserved word in a language. Some compilers will not even allow you to do this, but some will, and it may resolve the name clash in a way you or others do not expect. Do not use variables that differ in name by only a few letters, as this may result in accidentally writing incorrect code that compiles without errors.
Naming Choices
Choosing a good variable name means naming a variable in a way that will help the reader understand the program's design and purpose. This is different from naming conventions in that it can not be so strictly defined, and is concerned with individual variables as opposed to all variables.
It is best to avoid names that give no information as to how the variable is to be used, or simply tell the type of the variable. Examples are naming a variable something like data, buffer, info, string, etc. These don't tell the reader anything about the variable (of course a variable is data). Further, this is not always a trivial problem to solve, as a descriptive name may not be concise and that can be worse than a meaningless name. An example is an operation on a string that involves parsing and editing a string, then returning the modified string. In this case, naming the two strings "inputString" and "outputString" at least gives some information on how they are intended to be used. Even better would be to replace the word string with what the data is supposed to represent. For example if the code is modifying an address, the variables could be named "inputAddress" and "outputAddress." Another example of this is performing complicated sums of modifications of numbers. Consider the following code:
$total = $price * $qty;
$total2 = $total - $discount;
$total2 += $total * $taxrate;
$total3 = $purchase_order_value + $available_credit;
if ( $total2 < $total3 ) {
print "You can't afford this order.";
}
Even though this is not very complicated code, if one were to look at the end of it first, they would be forced to go back and read the beginning to grasp what was going on. This is a much better version:
$order_total = $price * $qty;
$payable_total = $order_total - $discount;
$payable_total += $payable_total * $taxrate;
$available_funds = $purchase_order_value + $availble_credit;
if ( $payable_total < $available_funds ) {
print "You can't afford this order.";
}
Similarly, often the meaning of a value is lost by using magic numbers. By using a literal numeric value instead of a named variable identifier, there can be confusing as to the meaning of the value. Although most programmers would recognize 3.14 as an approximation of Pi, it is an example of a value which could be defined as a constant first. By doing this, the programmer provides the reader with some information as to why and how the value is being used.
Whenever possible, it is good to use names relevant to the context of the program's domain. Similarly, it is important to realize whether or not a term used is indeed common knowledge of a domain or not. For example, if you are working on a database application that manages bank accounts, then "account" may be an appropriate word used to name an account record. If it is well documented and there is no other meaning of the word within the context then it will work. However, recognize that "account" has different or ambiguous meanings in other contexts. So, if you used the same word to name records in database of library users, make sure the word means the same thing in that context.
Along these lines, it is a good idea to use design pattern names in class that are meant to implement them. If you are writing a class that uses the Factory class, by naming it with the word Factory, it is immediately clear to other programmers familiar with that design patter what the class is supposed to do and roughly how it is going to do it. This helps greatly with maintenance. In contrast, consider if the same class had been named Creator. The programmer has a general idea the class is going to create things, but will still need to read through the code to realize its purpose and scope.
External Links
http://www.symbian.com/developer/techlib/v70sdocs/doc_source/DevGuides/EssentialIdioms/NamingConvs.guide.html
http://www.kamath.com/columns/squareone/so001_whatname1.asp
http://msdn.microsoft.com/en-us/library/aa260976(VS.60).aspx
http://chrisbensen.blogspot.com/2007/07/variable-names-to-avoid.html
http://blogs.msdn.com/marcelolr/archive/2005/08/04/Marcelo.aspx
http://www.oualline.com/style/c03.html
http://www.oreillynet.com/onlamp/blog/2004/03/the_worlds_two_worst_variable.html
http://perl.plover.com/varvarname.html
http://c2.com/cgi/wiki?BadVariableNames
http://www.objectmentor.com/resources/articles/naming.htm