Names

In order to tell a story, you have to have names: Jack and Jill, the bartender and the patron, or whatever. If you're going to describe how a program works, you have to name the parts, both the data and the functions. Names are a critical foundation upon which the story of your program is built.

Rule 2   All names should be descriptive and accurate.

• If a function finds the biggest element in a linked list, don't call it sort. It should be called something like find_max or get_biggest. You could even call it largest, omitting the ``find'' part. That would read nicely in calls like:

      swap(current,biggest(list));
  

  The preceding code obviously swaps the current list element with the biggest in the list.
• There are circumstances under which you might name a variable prev that will point to elements of linked list. You would do this when there is another variable called current or elt or something, and prev is the previous value of that other variable or is the preceding list element. But if that's not what the variable is, you have just misled your reader. This is terrible. I have seen it happen.
• Similarly, I have seen code to find the smallest element in a list in which the name for the current element of the list was biggest. It wasn't the biggest anything. Again, I was misled.
• By ``descriptive,'' I mean that the name of the variable should talk about the purpose or use of the variable. For example, you would never name a variable anInt; surely there is some better description available.
• Calling a variable count is little improvement. What is it counting? Why is it counting? If the explanation is too long for a variable name, it can be put in the documentation, but struggle to improve the variable name. Names like bucket_count or loop_count may need further explanation, but once explained, they are easy to understand and remember.
• There are, of course, variables that are truly generic. One example is indices used in for loops or for accessing arrays. We are all familiar with code like the following:

     for( int i=0 ; i<array_size; i++ )
        array[i] = 0;
  

  There is no need to get clever trying to name i, for two reasons. First, it is simple and needs no explanation. Secondly, we can see every use of the variable right before our eyes; mnemonic names are most important when a variable will be seen a long way from its initialization and documentation. For such variables, a generic name like i or x is acceptable. Note that this is not an exception to the rule: a generic name is, in fact, accurate and descriptive.
• Sometimes a more generic name is better for functions and their arguments as well. The following function swaps two pointers. It could be used in sorting, permutations, and other unanticipated uses. Therefore, the first declaration is better than the second, because the second is too specific:

  void swap( student_ptr & x, student_ptr & y)
  void swap_smallest( student_ptr & curr, student_ptr & small )
  {
     student_ptr temp = x;            // this name is fine, too.
     x = y;
     y = temp;
  }
  

• Data members need to be appropriately named as well. The only difference between them and variables is that data members will be accessed via a variable, so the name of the data member is always in a context. For example, the following is probably too cumbersome:

  class Student {
  public:
     char student_name[20];           // The name of the student 
  }
  
  Student best_student;               // The student with best GPA
  cout << best_student.student_name;  // This seems too long and unwieldy
  

  Everything seems okay until we get to that last line. Then we realize that, since the student_name data member is found in an object of type Student, it's redundant to include the ``student'' in the name. We might go with best.student_name but best_student.name seems better, and even best.name is fine. Descriptive names needn't be incredibly long.

Rule 3   Be consistent with capitalization and punctuation of names. Decide on a scheme and stick with it.

Because C and C++ are case-sensitive, you can distinguish different kinds of things with capitalization, but be careful about this, because humans are not always case-sensitive. How many times have you had to ask whether it's ``String.h'' or ``string.h''? People, particularly computer-people, can train themselves to be case-sensitive, but it's always easy to overlook.

Here are some rules that are in common use or that are reasonable.

• Constants are in all capital letters. For example, NULL is in all caps. Very often, TRUE and FALSE are done that way; C++ seems to be changing to lower case for these. Code that is substantially uppercase is ugly, so using all caps for variables that occur only every so often is best. Examples that might occur in your programs are ARRAYMAX or MAX_STUDENTS.
• User-defined types, which includes names of structures and classes, start with a capital letter. Thus, you might name your class Student or Node.
• Variables, functions, and data members start with a lower-case letters. Thus, you might have variables named best or head or whatever.

Creating new types--classes and structures--is more rare and important than naming a variable or function. Therefore, it's reasonable to signal this by a capital letter. Constants are usually even more rare, so the uppercase names will be few. At least, this is a sensible view, even if there are exceptions.

You can use other schemes if you prefer. Your book, for example, typically uses uppercase for new types, so they would write LIST or NODE. This is acceptable as well. However, do not forget to be consistent. Don't name one variable CURR and the next prev because they will look like completely different kinds of things, and the reader will be confused and then annoyed.

Note that a good name often has two or three words in it. The issue always arises how to separate them. For example, a variable representing the smallest list element should not be named smallestlistelement. Instead, it could be named smallest_list_element, separating the word by underscores, or smallestListElement, indicating word separation by capital letters. Both ways are commonly used, so use whichever you prefer. I think underscores are easier to read, but either is acceptable. As always, be consistent.