CSC/ECE 517 Fall 2010/ch5 5b mt

Variable Naming Conventions

It has been written, "[p]rograms must be written for people to read, and only incidentally for machines to execute."^[1] Variables, which hold the data for the program, are used in all computer programming languages and are used for various reasons; such as, holding the value of a constant, holding the value of something used many times throughout the program, or even used briefly for counting. The names used for each variable are more difficult to choose than simply making any letter or word combination. The rest of this article is dedicated to helping the novice programmer choose good variable names.

Introduction

A Variable^[2] is a name used within a program that holds the value of something that is known or unknown. For example, the variable "firstName" might be used to hold the string of letters that comprises a person's first name. The variable may or may not be set at the beginning of the program and it may change multiple times after being set. Naming conventions ^[3] are a set of rules used to guide the programmer when creating the names of variables. Thinking about a variable to hold first names again, if there were no naming conventions, then the variable could be named "fn". Context could allow a reader to understand the purpose variables, and in a user information form the variable "fn" could be understood to hold the person's first name. However, if the variable is used later in a concatenation, which is a joining of separate variables or ascii characters, it may be harder to follow what is being used. For example, after the user finishes filling out the account creation form the program creates a temporary password in a separate method. The code for this password is:

 tp = "1892" + fn + un + dc + td; 

In the password example above, can you figure out what each of the variables holds? Maybe or maybe not, but so can check yourself: the variable tp is the temporary password, fn is the user's first name, un is the username, dc is the date created, and td is today's date. This simple example should help you see the importance of using good variable names. Therefore, general naming conventions, which are incorporated by many languages, are used by a programmer to create a program that is easier to read ad understand its purpose. General naming conventions are not perfect; thus, many coding languages have adopted their own type of convention Additional Resources.

Popular Naming Conventions

To help establish consistency, a few variable naming conventions were created to give programmers a method for writing variable names. There are two main ways of thinking about naming variables - style and content. Style refers to what the variable looks like and content refers to the substance of the name. There are a few conventions that deal with the style of variables, which include single word names; white space, hyphens and underscores separating words and camel case. There are only two main conventions used that affect the content of the variable, and they are Hungarian notation and common sense.

Single Words

Often times a variable represents a very simple idea like name, location, address, or license. For simple programs, these single word variables work very well. However, more times than not, a program wants to split the information and put it in a database in a logical manner, like first name, last name, GPS coordinates, street address, driver license number, driver license state. So, if multiple words are needed to define the variables, other style mechanisms are needed.

White space

A white space is generally considered a delimiter for token parsing; thus it is not recommended for use in variable names. Furthermore, many language conventions do not allow white space because one can call or create many variables on one line with just a white space between them - int left motor right motor. In that example, some languages would create four variables, when the intention was to have just two variables, left motor and right motor. Therefore, one has to establish a non-white space system for a variable that has more than one word in it. For example, if one wants to reference a "First Name" data string, there are many different ways we could establish a variable name for this (e.g. fName, first_Name, FirstName, etc...).

Hyphens and Underscores

Hyphens '-' have been around since the beginning of programming with COBOL and LISP (i.e. END-OF-FILE). However, since some programming languages can subtract one string from another the hyphen was replaced by the underscore '_'. Underscores provide a good amount of near whitespace; thereby, making the separated words stand out easier. For example, date_of_birth is easier to read than dateofbirth. Underscores are also used as special variable identifiers when placed at the beginning of the variable (VB, C++, C#). Unfortunately, the technological advance from punch cards to dot-matrix printers and regular character set to ASCII has, at times, made the underscore unreadable, misaligned or sometimes merged with underlined text. Therefore, the next movement of variable styling went to camel case, even though hyphens and underscores are currently used in many programming languages.

Camel Case

Camel Case is a generic name for a naming style in which the variables have capital letters at the beginning of some or all of the words. The two most common forms of camel case are lower and upper camel case. Lower camel case format starts the variable name off with a valid, lowercase letter, and then the first letter of each new word is capitalized. This allows each word to be easily distinguished without injecting any unnatural characters into the variable name. For our "First Name" example, we would reference this as firstName. Upper camel case is the same as lower except that the first word is capitalized. Again, using the "First Name" example, the variable would read FirstName.

Hungarian Notation

Hungarian notation is a naming convention that was intended to be used in any language and is used to impact the content of the variable. There are two types of this notation, Systems and Apps. Hungarian Systems notation requires the variable to be prefixed by the data type of the variable's use. For example, a float number that is used to hold the value of the circumference of a circle would be defined as fCircleCircumference.

Hungarian Apps notation requires the purpose of the variable it's prefix. For example, the Apps variable name for a circle's circumference would be numCircleCircumference.

The two types of Hungarian notation are similar, but the easiest way to remember the them is through their difference. Systems notation looks at the specific type for the variable: l for long, f for float, d for double; whereas, Apps just uses the generic name: num for any number or str for a string.

In reference to our "First Name" example, we know that this variable will hold a string. A candidate Hungarian Apps notation variable name could be strFirstName.

Common Sense

When writing code in a program, whether established or just at the beginning, common sense should be used when creating variables. This means using full words or appropriate, commonly used abbreviations in the variable name. For example, a variable that holds the street address should be streetAddress and not strAddress because strAddress could be street address or string address in the case of Hungarian Apps notation. For more information on using common sense when naming variables see the Naming Variables section.

Universally Used Variables

There are commonly used variables that programmers use no matter what language he/she is coding in. The following list does not constitute acceptance of the variables as properly named. The most common are:

• i, j, k - used for counting especially in short code snippets
• x, y, z - used for holding the position of an object
• file - to indicate a placeholder for the location of a file
• dir - holds the string of a folder in a file system
• e - holds the value of the system error
• foo, bar, foobar - variables used in examples showing how to use new code in many languages

Naming Variables

As a previously written wiki article states "[c]hoosing a good variable name means naming a variable in a way that will help the reader understand the program's design and purpose"^[4]. You should have many goals when writing a program, the top two are below.

1. Does this program do what I need it to do?
2. After I no longer need to own the code, will other people be able to read my code and understand how it works.

The first goal is the most important because if the program does not do what it is advertised for, then no one will want to use it. Let's say that the code works exactly the way you want, and you posted it to the internet for all to use for free. As it will undoubtedly turn out, the code will most likely not be perfect and will require modifications to fit the needs of other people. If they look at your code and cannot figure out how the stuff that goes into the program comes out the way it does, they will be unhappy and your new support email box will be full. To circumvent some of the questions that may come your way, you can make your program more readable. The first step is to create variables with names that make sense. To help you out, there are a few things that you should and should not do as well as some key questions you should ask yourself when creating those variable names.

Do's And Don'ts

When picking your variable names, here are a few Do's and Don'ts to consider. ^[5]

• Do use meaningful words
• Do use intention-revealing names
• Do be descriptive
• Do keep consistent in your naming convention

• Don't ever name your variables, "data" ^[6]

• Don't use needless variables, e.g.
  • FORTY_TWO = 42;
  • x = 4; one_more_than_x = x + 1

• Don't give up!

Questions to Ask

There are some questions that you should ask yourself before you decide on a naming scheme for your variables. These questions when answered should give the programmer the needed answers for the naming scheme.^[7]

• Will my variable names by understood?
• Will they provide information to the maintenance programmer?
• Will they be easy to get right as more code is written?
• Will they get confused with one another?
• Will they fall in line with the language's naming conventions?

Code Readability Example

Armed with these given tools, an example that demonstrates good and bad variable naming conventions is given. Which example is good and which one is bad?

The purpose of the given code is to read in an online food order and give some information back to the customer.

Example 1

Example 2

numberHamburgers - 1; numberCheeseBurgers - 1; numTacquitos - 9; sizeFries[] - [3, 2, 3]; typeAndSizeDrink[] = [(Coke,3), (DrPepper,2)]; subTotalSandwiches = numberHamburgers *priceHamburgers + numberCheeseBurgers*priceCheeseBurgers + numberTacquitos*priceTacquitos; . . . subTotal = subTotalSandwiches + subTotalFries + subTotalDrink; tax = subTotal * 0.625; total = subTotal + tax; output("Your total is " + total); output("Have a great day!);

numHams - 1; numCB - 1; numT - 9; F[] - [3, 2, 3]; d[] = [(Ck,3), (dPr,2)]; Ss = numHams*pHams + numCB*pCB + numT*pT; . . . S = Ss+Sf+Sd; T = S*0.625; t = S + T; out("Your total is " + t); out("Have a grate day!);

Example 1 is clearly the most readable and easiest to understand code to follow. The variables all have the same coding style and content. However, notice that Example 2 uses the same coding style throughout the variable definitions. It is compact and everything fits on one line. So, even with the same coding style used throughout the code, the name itself needs to be understandable for the overall code to be understandable.

Conclusions

Variables are inevitable in programming. The naming of variables must be taken with caution so that they make sense to any who read through the code. When creating names of variables the author should take into account the language of the code, the purpose of the variable, and the type of value the variable will hold. Adhering to naming conventions is not a requirement, but they are merely guides that a programmer can use to determine the best way to name the program's variables.

References

1. Abelson, H., Sussman, G.J. (1996). Structure and Interpretation of Computer Programs - 2nd Ed. Cambridge: The MIT Press.

2. Wikipedia. 21 October 2010. Variable (programming). Retrieved November 03, 2010, from Wikipedia: http://en.wikipedia.org/wiki/Variable_%28programming%29

3. Wikipedia. 03 November 2010. Naming convention (programming). Retrieved November 03, 2010, from Wikipedia:http://en.wikipedia.org/wiki/Naming_convention_%28programming%29

4. Wikipedia. 07 July 2008. Variable Naming in Programming. Retrieved November 22, 2010, http://pg-server.csc.ncsu.edu/mediawiki/index.php/CSC/ECE_517_Summer_2008/wiki2_2_rapodraz

5. Skrien, D. (2009). Object-Oriented Design Using Java. New York: McGraw-Hill.

6. Lester, A. 06 March 2004. The world's two worst variable names. Retrieved November 03, 2010, from O'REILLY: http://www.oreillynet.com/onlamp/blog/2004/03/the_worlds_two_worst_variable.html

7. Well House Consultants LTD. (n.d.). What makes a good variable name?. Retrieved November 03, 2010, from http://www.wellho.net/solutions/general-what-makes-a-good-variable-name.html

Additional Resources

• Ruby naming conventions - http://rubylearning.com/satishtalim/ruby_names.html
• Sun Java naming conventions - http://www.oracle.com/technetwork/java/codeconventions-135099.html#367
• .NET 4 naming conventions - http://msdn.microsoft.com/en-us/library/ms229045.aspx
• C++ naming conventions - http://www.cprogramming.com/tutorial/style_naming_conventions.html
• Hungarian Notation - http://en.wikipedia.org/wiki/Hungarian_notation