CSC/ECE 517 Fall 2010/ch5 5b mt

Variable Naming Conventions

As a popular saying goes, source 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 used briefly for counting. The names used for each variable are more difficult to choose than simply making any word 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 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 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.

||An example of multiple cites for the same resource ^{[1] [1]} If it doesn't have multiple cites for the same resource just leave off the a and b

||

The Good and The Bad

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 (include reference number here).

 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.

---

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.

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.

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

---

Dos And Don'ts

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

• Do use meaningful words
• Do use intention-revealing names (p 84 java book)
• Do be descriptive
• Do keep consistent in your naming convention

• Don't ever name your variables, "data" ( http://www.oreillynet.com/onlamp/blog/2004/03/the_worlds_two_worst_variable.html )

• Don't use needless variables, eg.
  • FOURTY_TWO = 42;
  • x = 4; one_more_than_x = x + 1

• Don't give up!

Questions to Ask

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

(Source http://www.wellho.net/solutions/general-what-makes-a-good-variable-name.html )

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. ^{a, b} Author last, FI. (2010, April 26). Title of webpage. Retrieved October 15, 2010, from site name (Github): http://github.com/

Additional Resources

• 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
  • Hungarian notation was invented by Microsoft programmer Charles Simonyi.
  • While Hungarian notation can be applied to any programming language and environment, it was widely adopted by Microsoft for use with the C language, in particular for Microsoft Windows