CSC/ECE 517 Fall 2010/ch5 5b mt

Variable Naming Conventions

Dr. Donald Knuth once said, "[s]ource code is meant to be read by humans; it is only a coincidence that it is also interpreted by machines." Holding the data for source code, variables 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 and convention-styles for when writing their code.

Introduction

A Variable^[1] 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 not be set at the beginning of the program and it may change multiple times after being set. Naming conventions ^[2] are a set of rules used to guide the programmer when creating the names of variables. Using the previous example, if there were no naming conventions, the variable could be named "fn", which is ambiguous and would be hard to follow when reading through many lines of code. Therefore, general naming conventions, which are incorporated by many languages are needed to aid the ability to follow the code without having the author present. General naming conventions are not perfect; thus, many coding languages have adopted their own type of convention. Furthermore, there are universally used variables and special types of variables that are used without regard for a language type.

Popular Naming Conventions

To establish consistency, several conventions have been popularized to give programmers a method for writing variable names. For example, since in most programming languages white space is considered a delimiter for token parsing, one has to establish a non-whitespace system for separating two adjacent words for one variable. 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...).

Camel Case

The format for Camel Case is to start the variable name off with a valid, lowercase letter, and then for each word afterward, capitalize its first letter. 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.

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

---

Dos And Don'ts

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

• 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" ^[3]

• Don't use needless variables, eg.
  • FOURTY_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.^[5]

• 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?

The Good and The Bad

Armed with these given tools, an example that demonstrates three types of naming is presented below. The first is an example of bad naming conventions.

Imagine you are diving into someone's code, and you find something like this...

 1  function mystery_function(var1, var2):
 2      for each vertex v in var1:
 3          var3[v] := infinity ;
 4          var4[v] := undefined ;
 5      end for ;
 6      var3[var2] := 0 ;
 7      var5 := the set of all nodes in var1 ;
 8      while var5 is not empty:
 9          var7 := vertex in var5 with smallest var3[] ;
10          if var3[var7] = infinity:
11              break ;
12          fi ;
13          remove var7 from var5 ;
14          for each neighbor var6 of var7:
15              var8 := var3[var7] + dist_between(var7, var6) ;
16              if var8 < var3[var6]:
17                  var3[var6] := var8 ;
18                  var4[var6] := var7 ;
19              fi  ;
20          end for ;
21      end while ;
22      return var3[] ;
23  end mystery_function.

Clearly, code without meaningful variables greatly complicates reading what the algorithm is supposed to do. Even with a slightly better example, using really short variable names, can be difficult to understand.

 1  function mystery_function(G, s):
 2      for each vertex v in G:
 3          d[v] := infinity ;
 4          p[v] := undefined ;
 5      end for ;
 6      d[s] := 0 ;
 7      Q := the set of all nodes in G ;
 8      while Q is not empty:
 9          u := vertex in Q with smallest d[] ;
10          if d[u] = infinity:
11              break ;
12          fi ;
13          remove u from Q ;
14          for each neighbor v of u:
15              a := d[u] + dist_between(u, v) ;
16              if a < d[v]:
17                  d[v] := a ;
18                  p[v] := u ;
19              fi  ;
20          end for ;
21      end while ;
22      return d[] ;
23  end mystery_function.

Finally, here is the same algorithm, with the original variable names from the source-example ^[6].

 1  function mystery_function(Graph, source):
 2      for each vertex v in Graph:
 3          dist[v] := infinity ;
 4          previous[v] := undefined ;
 5      end for ;
 6      dist[source] := 0 ;
 7      Q := the set of all nodes in Graph ;
 8      while Q is not empty:
 9          u := vertex in Q with smallest dist[] ;
10          if dist[u] = infinity:
11              break ;
12          fi ;
13          remove u from Q ;
14          for each neighbor v of u:
15              alt := dist[u] + dist_between(u, v) ;
16              if alt < dist[v]:
17                  dist[v] := alt ;
18                  previous[v] := u ;
19              fi  ;
20          end for ;
21      end while ;
22      return dist[] ;
23  end mystery_function.

So finally, with meaningful variable names in place, it is much easier to understand the purpose of the code. In fact, many may recognize it as Dijkstra's algorithm. Comparing this well-named example to our first example shows just how important naming can be when writing code.

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. Wikipedia. 21 October 2010. Variable (programming). Retrieved November 03, 2010, from Wikipedia: http://en.wikipedia.org/wiki/Variable_%28programming%29 2. Wikipedia. 03 November 2010. Naming convention (programming). Retrieved November 03, 2010, from Wikipedia:http://en.wikipedia.org/wiki/Naming_convention_%28programming%29 3. 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 4. Skrien, D. (2009). Object-Oriented Design Using Java. New York: McGraw-Hill. 5. 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 6. Wikipedia. 28 October 2010. Dijkstra's algorithm. Retrieved November 03, 2010, from Wikipedia: http://en.wikipedia.org/wiki/Dijkstra%27s_algorithm#Pseudocode source-example

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