C vs. C++ features Case Selection Documentation Entry & exit points Indentation Introduction Length of a subprogram Logical structure of a subprogram Loop style Magic Numbers Recursion - when to use it, when not Selection of Action Side Effects Single entry, single exit style Space Wraparound

Acknowledgments: To teachers and writers of good code for the lessons they have imparted and their examples of elegance and clarity; and to writers of bad code for their rich legacy of atrocities.

Introduction

This page is designed to advise on some of the do's and don'ts of good programming style. It is motivated by the conviction that computer programmers should not have for the only goal of a software development project that the program work correctly. Don't get me wrong: the program should work correctly. But there are very practical benefits to developing good programming style (for my students, one is keeping my blood pressure down while I grade your program). A program written in good style is usually easier to understand, debug, and update, than the same program would be if written in bad style. In professional software development, programs are constantly being modified to correct errors, expand functionality, meet changing specifications, improve efficiency, etc. In order that these be done correctly and efficiently, it's important that the source code be easily read and understood.

C vs. C++ features

The C++ programming language is built on a foundation of the C programming language, with features added on for the purpose of building a better programming language.  Many tools found in C++ are meant to replace analogs in C; in most cases, the C++ tools are stylistically (and, in some cases, semantically) superior.  Examples, in which the C++ tool is generally easier to write and understand than its C analog, include the following:

Often, students use the inferior C tools.  This can create several problems, including:

• Degradation of your program by use of the inferior tool.
• The practice may be due to the student having learned C before the current course, and wishing to continue using old habits.  In our field, those who don't adapt to change, don't advance professionally. Students should cultivate the habit of adopting superior practices when they learn them.
• Often, the use of code that is distinctly in the C style is copied.  Some copying is cheating; other copying is legal research.  When a professor in a programming class reads a student's program containing substantial code in a style the professor has cautioned students not to use, it's natural to wonder if the student actually wrote the code. Even if your copying is legal research, the use of inferior C tools is at best laziness.

Documentation

It has been said that programmers who do not document their code are indispensable, and unpromotable. They are indispensable because without proper documentation, it's likely that nobody else will understand their code. They are unpromotable for the same reason: you can't become a project leader if you don't yourself practice a fundamental of teamwork, namely, making your code understandable to your project teammates.

Proper documentation in a program should include the following elements:

• Identification of the programmer or team of programmers. For a student, this serves the obvious purpose of enabling an instructor to assign a grade. For a professional, this enables a reader of the listing to find a good source of information about a program.
• Identification of the "client" of the program. For a student, this is typically a course. For a professional, it may be a business client, another department within the organization employing the programmer, or a mass market. Particularly in the case of a more limited user group such as a department within an organization, the client can also be a useful source of information about the program.
• The date (could be approximate, e.g., Spring, 2006) the program was written, and, when relevant, its version and revision history.
• A brief statement about what the program does.
• Explanation of all major sections of the program. For example, in a C++ program, every class and every function should be explained (an exception may be justified for a function with a very simple listing whose name explains what the function does).
• When relevant, explanation of complex logic. For example, a calculation that uses a non-obvious mathematical technique should have that technique explained.

There are other issues of good documentation besides the use of comment/remark statements. For example, the programmer's choices of identifiers can do a lot to improve or harm understanding of code. Variables, function names, etc., should be chosen to suggest what they represent. Compare, for example, the following snippets of code:

float s, t, t1;
   .
   .
   .
t1 = s + t;

float subtotal, tax, total;
   .
   .
   .
total = subtotal + tax;

Logically, these two code fragments are identical. However, the one on the right is written in superior style, because its identifiers have been chosen to document their respective purposes within the code.

See the related issue of Magic Numbers.

Indentation

The indentation at the left margin of a line of code should indicate the block level of the statement. Nested statements should be indented more than higher-level (unnested) statements. Further, a continuation line should be indented more than the line that starts the statement. These practices help clarify a program's structure. Consider the fragments below, in which the version on the right is better than the version on the left:

   for (i = 0; i < size; i++) {
entry[i] = blah(i);
   cout << endl << i << ") "
   << entry[i] << endl;
       } // end for

   for (i = 0; i < size; i++) {
      entry[i] = blah(i);
      cout << endl << i << ") "
           << entry[i] << endl;
   } // end for

The superiority of the style used on the right is observed in the following:

• The two statements in the body of the for loop begin with identical indentation, and both of these statements are indented more than the indentation of the for line and the loop's ending line. Thus, the block level structure of the code fragment is clarified -- the indentation distinguishes between the loop's body and its beginning and ending lines.
• The second line of the cout statement is indented more than the first, emphasizing that the second line is "subservient to" the first (this is not the same, but is analogous to, being part of a nested block).

I encourage using a "top-down" approach. A subprogram (particularly, the main function in a C++ program) that directs complex action should have a listing that outlines the totality of the actions managed by the subprogram. When we combine this outlook with the advice given elsewhere in this document to keep the listing of each subprogram short, we can deduce that it's a good idea to extract lower-level details of a major subtask managed by a function so that such a subtask has its own subprogram that can be called upon by the current subprogram. This approach also facilitates the view of a subprogram as doing "one job," even if that "one job" involves managing several other "jobs."

For example: Here's a situation that often arises in student programs. A main function calls upon a menu function that both presents a menu to the user and acts upon the user's choice. As a result, a reader of the main function doesn't see how the program acts on the user's choice. A better structure: have the main function call upon a menu function that returns (preferably via a reference parameter, not via a return statement, as the latter method likely would represent a side effect) the user's choice to the main function, and have the main function contain the code (which could be a call to a separate function with, say, a switch structure to select the appropriate action) that shows how the program responds to the user's choice.

 
   int x, y;
   .
   .
   .
   for (x = 5; x <= TOPVALUE; x += 5) {
      y = x * x;
      cout << x << '\t' << y << endl;
   } // end for

   node * head;
   node * at;
   .
   .
   .        
   for (at = head; at /* != NULL */ ; at = at->next)
      cout << at->name << endl;

   node * head;
   node * at;
   .
   .
   .        
   at = head;
   while (at)   // while (at != NULL)
   {  cout << at->name << endl;
      at = at->next;
   } // end while

Recursion - when to use it, when not to use it

Recursion is when a subprogram calls upon itself, either directly or circularly. Circular recursion takes place when there is a list of subprograms s₀, s₁, ..., s_n-1 such that for each index i, s_i calls upon s_{(i+1) mod n} -

Typical good uses of recursion are in "Divide and Conquer" algorithms.  These are algorithms for which a large problem is divided up into smaller problems of the same type; each of the smaller problems is solved; and the partial solutions are "stitched together" to obtain a solution to the original, large problem.  (In the following, you need to know that merging two sorted lists means combining the lists into a single sorted list.)  For example, the Merge Sort algorithm for sorting data may be expressed as follows:

Notice that recursion is a form of looping.  For example, in the discussion above, when we apply the algorithm recursively to L1, the list L1 has at least 2 items then it is divided into smaller lists, say, L11 and L12; if L11 has at least 2 items, it is subdivided into, say, L111 and L112; etc.

Because direct recursion (a subprogram calling itself directly) is a form of looping, it can often be avoided when its only motivation is looping.  Languages like C++, BASIC, COBOL, and Visual Basic provide other loop forms for programmers to use that will often be more clear than recursion, so that, unless there is a motivation other than looping (such as divide-and-conquer), it may be preferable to avoid direct recursion.  (There are programming languages such as LISP and PROLOG in which recursion is the primary form of looping - in such languages, it may be impossible or undesirable to avoid direct recursion even when looping is the only motivation.)

Circular recursion is rarely necessary, and often is difficult to understand.  Unfortunately, many beginners use circular recursion where a more conventional form of looping would be much easier to understand.  Consider the following forms, in which the example on the right is preferable:

   .
   .
   .
   void againQuery();
   int main() {
   .
   .
   .
   againQuery();
   return 0; 
   } // end main
   .
   .
   .
   // - - - - - - -
   void againQuery()
   {  bool repeating;
      char response;
      .
      .
      .
      cout << "Another round? (y/n): ";
      cin >> response;
      .
      .
      .
      repeating = (response == 'Y') || (response == 'y');
      if (repeating)
         main();  // here's circular recursion
   } // end againQuery
   

   .
   .
   .
   void againQuery(bool &);
   int main() {
   bool repeating;
   .
   .
   .
   do {
      .
      .
      .
      againQuery(repeating);
   } while (repeating); // end do
   return 0; 
   } // end main
   .
   .
   .
   // - - - - - - -
   void againQuery(bool & repeating)
   {  char response;
      .
      .
      .
      cout << "Another round? (y/n): ";
      cin >> response;
      .
      .
      .
      repeating = (response == 'Y') || (response == 'y');
   } // end againQuery
   

Logically, these code fragments are identical. However, the version on the right is easier to understand, because its loop structure is explicit in the main function.  By contrast, the version on the left hides its looping - you must read main and againQuery together in order to understand that the actions of main repeat.  It's easier to read one function at a time than two (or more) functions together.  Therefore, circular recursion should be avoided unless there is some powerful reason other than looping (which, for most programmers, will be a rare event) for using it.

    if (choice == 1)   
        action1;
    if (choice == 2)
        action2;
    if (choice == 3)
        action3;
    if (choice == 4)
        action4;

    switch (choice) {
      case 1: {
        action1;
        break; } // end case 1
      case 2: {
        action2;
        break; } // end case 2
      case 3: {
        action3;
        break; } // end case 3
      case 4: {
        action4;
        break; } // end case 4
    } // end switch

A side effect introduces the potential for a nasty surprise in the behavior of a program. See this essay for more information on this topic.

• Don't use goto statements. If the target of a goto is not at the start of its block, then its block has two entry points; if the goto statement is not at the end of its block, then its block has two exit points. The goto statement can also have other undersirable effects on the understanding of the listing; for example, see the Loop Style section.
• Don't use exit statements. Since a typical C++ program ends at a return 0; statement at the end of its main function, the use of an exit statement provides a second exit point from the program.
• Don't use break statements except to end a case of a switch structure. To use a break, say, to exit a loop, provides the loop with a second exit point.

Some argue for exceptions to the rules stated above in order to simplify the flow of control amidst complex code. For example, some argue that if main calls on blah, which calls on ..., which calls on gallumph, and an unusual error is detected by the code of the latter function that makes further processing within the program pointless, it is easier for the programmer to use an exit statement to end the run of the program than to provide appropriate if statements, one in each of the chain of functions alluded to above, to provide "normal" exit from the main function's end-of-listing or return 0; statement. Since student exercises rarely get complex enough to make a strong argument along these lines, I prefer my students to follow the guidelines above.

for(i=0;i<LISTSIZE;i++){
   a[i]=b[i]+nu(i,j,k);
   cout<<a[i]<<endl;
}//end for

for (i = 0; i < LISTSIZE; i++) {
   a[i] = b[i] + nu(i, j, k);
   cout << a[i] << endl;
} // end for

  cout << "Today's winner is " << player[i
ndex].firstName << ' ' << player[index].la
stName << ".\n";

  cout << "Today's winner is " <<
       player[index].firstName << ' ' <<   
       player[index].lastName << ".\n";

Reference

[Dijkstra] E.W.G. Dijkstra, "Go To statement considered harmful," Communications of the Association for Computing Machinery 11, 3 (Mar., 1968), pp. 147-148;

          Online at http://www.cs.utexas.edu/users/EWD/ewd02xx/EWD215.PDF

Dijkstra's letter was reprinted with some paraphrasing as

"(A Look Back at) Go To Statement Considered Harmful," Communications of the Association for Computing Machinery 51, 1 (Jan., 2008), pp. 7-9.

          Online at http://mags.acm.org/communications/200801/