CSC/ECE 517 Fall 2010/ch5 5b mt

From Expertiza_Wiki
Jump to navigation Jump to search

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.

Camel Case

Camel Case is a generic name for a naming pattern that includes 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 for each word afterward, its first letter 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. There are two types of this notation, Systems and Apps. 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 sprocket would be defined as fSprocketCircumference. Apps notation requires the purpose of the variable it's prefix. Using the previous example, the Apps definition would be numSprocketCircumference.

In reference to our "First Name" example, notice how we wish to elaborate that this variable will hold a string. A candidate Hungarian convention 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 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. Notice that Example 2 uses the same coding style. So, even with a coding style used throughout the code, the content, or words in the variable, needs 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

Retrieved from "https://wiki.expertiza.ncsu.edu/index.php?title=CSC/ECE_517_Fall_2010/ch5_5b_mt&oldid=42353"