C++ Style Tips

Programming style is a personal thing, and a difficult one to learn. I have seen a programmer produce completely unreadable code, bad enough to make other people swear at their screens, while sincerely attempting to generate an exceptionally clear and simple result.

Here are some hints for writing better C++ programs, in no particular order:

• Write only one statement per line.
• Limit lines to 80 characters maximum.
• When using line comments (i.e., comments at the end of a line of code), be sure that the comments on different lines begin in the same column. This makes it much easier to separate comments from code.
• Set up your editor so that tab stops are every 8 characters, because that is (a) an industry standard and (b) how we will be looking at your programs; if you use a different tab width your programs will look wrong to us and we will grade you down for it. By "tab stops" we mean the way that your editor displays the ASCII TAB (control-I) character. This may be different from the indentation produced by the Tab key. In both vi and emacs, 8-character tab stops are the default, but many Windows-based editors violate the standard by using 4-character tabs.

  If your editor produces files with 4-character tab stops, you can clean up the file with the following commands:

  % expand -4 < foo.cc | unexpand -a > foo_clean.cc % mv foo_clean.cc foo.cc

• 2- to 5-space indentation is preferred. 1-space indentation is unacceptable, as is anything over 8 spaces.
• Be liberal with whitespace! Put blanks around operators and blank lines between major sections of code. Look at your code from a distance, and see if you can identify major sections just by the patterns of light and dark. Use the same technique at a closer range to see whether you can easily separate statements into their components.

  At the same time, don't go too crazy. Excessive spacing (e.g., many blank lines inside a function) hides structure just as effectively as no spacing at all.

• Give your variables descriptive names that are neither too short nor too long. Examples of poor names are i (too short and not descriptive), pointer_to_left_side_of_the_maze (too long), harvey (not descriptive), and pointerToInteger (either redundant or misleading, depending on the declaration).
• Don't use names beginning with "my". The word "my" isn't generally meaningful, since it can refer to any human in the world. If you want to personalize a class or variable name, use your initials or something else that is reasonably unique. Even better is to give your class or variable a name that describes its function, not its authorship.
• Don't create unnecessary classes. Unlike Java, C++ does not require every function to be a class member. You don't have to create dummy "wrapper" classes to make a function work.
• When you are creating a general-purpose class, be sure that the functions you write are also general-purpose. A string class shouldn't normally have a special function that is only useful for one homework assignment.
• Be consistent with your naming style. Don't mix underscores with capitalization-style separation (i.e., the same program should not have variables named NumberOfProfessors, numberOfStudents, and number_of_staff).
• Choose a brace style and be slavishly consistent with it. There are two traditional styles, the so-called K&R style:

              while (i >= 0) {
                  ...
              }
  	

  and Allman style:

              while (i >= 0)
              {
                  ...
              }
  	

  Professor Kuenning prefers a third style (you're welcome to ask why, outside of class):

              while (i >= 0)
                  {
                  ...
                  }
  	

  Yet a fourth style is available in the C++ mode of emacs:

              while (i >= 0)
                {
                  ...
                }
  	

  We don't care which of these you use, so long as you stick with it. Don't invent a fifth style unless you're prepared to argue why it's outstandingly good.
• Be very careful about putting the body of a compound statement on the same line as the conditional part. For example, at first glance the following code:

              if(i==0) j++;
  	

  looks very similar to an assignment statement or complex function call (a problem that is aggravated by the lack of whitespace). It's much better to put the consequent on a separate line so that the indentation makes it clear that a test is happening:

              if (i == 0)
                  j++;
  	

  Remember that whitespace is cheap!
• Avoid constants. As a general rule, the only numeric constants that should appear in your program are zero and one. Everything else should have a name. For example, instead of int values[100];, use:

  	    const int MAX_VALUES = 100;
  	    ...
  	    int values[MAX_VALUES];
  	

  This has two benefits: it makes your code much clearer (when the reader sees a loop limit of 100, he or she doesn't have to wonder whether it's a loop to MAX_VALUES or to the number of centimeters in a meter), and it makes it much easier to change the constant later (if you need to double the size of the values array, you only have to change one line, instead of searching the entire program for every occurrence of "100" -- and forgetting the place where you used 99 instead of 100-1).
• Avoid the goto statement at all costs. If you can't figure out how to get along without a goto, ask your professor or one of the graders. A goto is never unavoidable, although there is one situation (which should not arise in your assignments) where it serves as a multilevel break and is therefore acceptable.
• Every variable, except loop indices, should have a one-line comment that expands on its name to help the reader understand its purpose.
• Every function should have a comment in front of it that describes what it does, what it expects of the caller, what it returns, and any surprises it might have in store (such as modifying one of its arguments).
• Use comments judiciously. Don't put in so many comments that it's hard to find the code, but be sure to describe everything that you're doing (at a high level). For example, write like this:

              // Initialize array to zero before setting nonzero values
              for (int i = 0;  i < ARRAY_SIZE;  i++)
                  values[i] = 0;
  	

  rather than this:

              for (int i = 0;             // i is loop index, start at zero
                i < ARRAY_SIZE;           // ARRAY_SIZE is how far loop goes
                i++)                      // Increment i
                  values[i] = 0;          // Set ith value to zero
  	

• When you overload operators, be sure to give them a meaning that will be intuitive to a person unfamiliar with your code. For example, you should not overload the == operator to do anything other than compare for equality, even if a different function might be useful in your code. Remember that overloading is intended to enhance readability, not to make your code easier to type. Exception: There are some operator overloads that are so common that they are allowable even though you might find them a bit odd. Examples include the string concatenation operator +, and the iterator operators ++ and -- (for stepping), * and [] (for access to data), and bool casts (for testing).

These are general guidelines only; more on coding style will be covered in class. As discussed in class, a readable program is more important than a working one, if you have to make a choice.

© 2001, Geoff Kuenning

This page is maintained by Geoff Kuenning.