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. The code for this password is:

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

In the password example above, 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 to aid a person's ability to comprehend the code without having the author present. General naming conventions are not perfect; thus, many coding languages have adopted their own type of convention [#Additional Resources]. Furthermore, there are universally used variables and special types of variables that are used without regard for a language type.

Popular Naming Conventions

To help establish consistency, several variable naming conventions have been created to give programmers a method for writing variable names. For example, since a white space is generally considered a delimiter for token parsing, one has to establish a non-whitespace 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, firstName, FirstName, etc...). 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.

Hyphens and Underscores

Hyphens and underscores are each a type of variable name styling. 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

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.

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. However, you wrote the perfect code and others love it. Reality check!!!! The code is most likely not 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, 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.^[6]

• 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;  for sizeFries[].each do |f|   if f = 3 then subTotalFries += priceLargeFry;   elseif f = 2 then subTotalFries += priceMediumFry;   else subTotalFries += priceSmallFry;  end  for typeAndSizeDrink[].each do |d|   if d(0,1) = 3 then subTotalDrink += priceLargeDrink;   elseif d(0,1) = 2 then subTotalDrink += priceMediumDrink;   else subTotalDrink += priceSmallDrink;  end subTotal = subTotalSandwiches + subTotalFries + subTotalDrink; tax = subTotal * 0.625; total = subTotal + tax; output("Your total is %l", 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;  for F[].each do |f|   if f = 3 then Sf += pF3;   elseif f = 2 then Sf += pf2;   else Sf += pf1;  end  for d[].each do |d|   if d(0,1) = 3 then Sd += pd3;   elseif d(0,1) = 2 then Sd += pd2;   else Sd += pd1;  end S = Ss+Sf+Sd; T = S*0.625; t = S + T; out("Your total is %l", total); 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