Ideally, a program serves two purposes: First, it presents the computer with a set of instructions, and second, it provides the programmer with a clear, easy-to-read description of what the program does.

Example 2-1 contains a glaring error. It is an error that many programmers still make and one that causes more trouble than any other problem. The program contains no comments .

A working but uncommented program is a time bomb waiting to explode. Sooner or later someone will have to modify or upgrade the program, and the lack of comments will make the job ten times more difficult. A well-commented, simple program is a work of art. Learning how to comment is as important as learning how to code properly.

C++ has two flavors of comments. The first type starts with /* and ends with */. This type of comment can span multiple lines as shown:

/* This is a single-line comment. */
/* 
 * This is a multiline comment.
 */

The other form of comment begins with // and goes to the end of the line:

// This is another form of comment.
// The // must begin each line that is to be a comment.

The advantage of the /* */ comment style is that you can easily span multiple lines, whereas with the // style you have to keep putting the // on each line. The disadvantage of /* */ is that forgetting a */ can really screw up your code. (Remember this because it’s the answer to one of the questions later in the book.)

Which flavor should you use? Whichever one makes your program as clear and as easy to read as possible. Mostly, it’s a matter of taste. In this book we use the /* */ style comments for big, multiline comments, and the // style is reserved for comments that take up only a single line.

Whatever comment style you decide to use, you must comment your programs. Example 3-1 shows how the “hello world” program looks after comments are added.

/********************************************************
 * hello -- program to print out "Hello World".         *
 *      Not an especially earth-shattering program.     *
 *                                                      *
 * Author: Steve Oualline                               *
 *                                                      *
 * Purpose: Demonstration of a simple program           *
 *                                                      *
 * Usage:                                               *
 *      Run the program and the message appears         *
 ********************************************************/
#include <iostream>

int main(  )
{
    // Tell the world hello
    std::cout << "Hello World
";
    return (0);
}

In this program, the beginning comments are in a box of asterisks (*) called a comment box. This is done to emphasize the more important comments, much like bold characters are used for the headings in this book. Less important comments are not boxed. For example:

    // Tell the world hello
    std::cout << "Hello World
";

/******************************************************** 
 ******************************************************** 
 ******** WARNING: This is an example of a        ******* 
 ********   warning message that grabs the        ******* 
 ********   attention of the programmer.          ******* 
 ******************************************************** 
 ********************************************************/ 

//------------> Another, less important warning <--------

//>>>>>>>>>>>>  Major section header  <<<<<<<<<<<<<<<< 

/******************************************************** 
 * We use boxed comments in this book to denote the     * 
 * beginning of a section or program                    * 
 ********************************************************/ 

/*------------------------------------------------------* 
 * This is another way of drawing boxes                 * 
*------------------------------------------------------*/ 

/* 
 * This is the beginning of a section 
 * ^^^^ ^^ ^^^ ^^^^^^^^^ ^^ ^ ^^^^^^^ 
 * 
 * In the paragraph that follows we explain what 
 * the section does and how it works. 
 */ 

/* 
 * A medium-level comment explaining the next  
 * dozen or so lines of code.  Even though we don't have 
 * the bold typeface we can **emphasize** words. 
 */ 

// A simple comment explaining the next line

To write a program, you must have a clear idea of what you are going to do. One of the best ways to organize your thoughts is to write them down in a language that is clear and easy to understand. Once the process has been clearly stated, it can be translated into a computer program.

Understanding what you are doing is the most important part of programming. I once wrote two pages of comments describing a complex graphics algorithm. The comments were revised twice before I even started coding. The actual instructions took only half a page. Because I had organized my thoughts well (and was lucky), the program worked the first time.

Your program should read like an essay. It should be as clear and easy to understand as possible. Good programming style comes from experience and practice. The style described in the following pages is the result of many years of programming experience. It can be used as a starting point for developing your own style. These are not rules, but only suggestions. The only rule is this: Make your program as clear, concise, and simple as possible.

At the beginning of the program is a comment block that contains information about the program. Boxing the comments makes them stand out. The list that follows contains some of the sections that should be included at the beginning of your program. Not all programs will need all sections, so use only those that apply.

The format of your beginning comments will depend on what is needed for the environment in which you are programming. For example, if you are a student, the instructor may ask you to include in the program heading the assignment number, your name, student identification number, and other information. In industry, a project number or part number might be included.

Comments should explain everything the programmer needs to know about the program, but no more. It is possible to overcomment a program. (This is rare, but it does happen.) When deciding on the format for your heading comments, make sure there is a reason for everything you include.

:abbr #b /************************************************
:abbr #e ************************************************/

/************************************************

The actual code for your program consists of two parts: variables and executable instructions. Variables are used to hold the data used by your program. Executable instructions tell the computer what to do with the data. C++ classes are a combination of data and the instructions that work on the data. They provide a convenient way of packaging both instructions and data.

A variable is a place in the computer’s memory for storing a value. C++ identifies that place by the variable name. Names can be any length and should be chosen so their meaning is clear. (Actually, a length limit does exist, but it is so large that you probably will never encounter it.) Every variable in C++ must be declared. (Variable declarations are discussed in Chapter 9.) The following declaration tells C++ that you are going to use three integer (int) variables named p, q, and r:

int p,q,r;

But what are these variables for? The reader has no idea. They could represent the number of angels on the head of a pin, or the location and acceleration of a plasma bolt in a game of Space Invaders. Avoid abbreviations. Exs. abb. are diff. to rd. and hd. to ustnd. (Excess abbreviations are difficult to read and hard to understand.)

Now consider another declaration:

int account_number;  
int balance_owed;

Now we know that we are dealing with an accounting program, but we could still use some more information. For example, is the balance_owed in dollars or cents? It would be much better if we added a comment after each declaration explaining what we are doing.

int account_number;      // Index for account table
int balance_owed;        // Total owed us (in pennies)

By putting a comment after each declaration, we in effect create a mini-dictionary where we define the meaning of each variable name. Since the definition of each variable is in a known place, it’s easy to look up the meaning of a name. (Programming tools, such as editors, cross-referencers, and grep, can also help you quickly find a variable’s definition.)

Units are very important. I was once asked to modify a program that converted plot data files from one format to another. Many different units of length were used throughout the program and none of the variable declarations was commented. I tried very hard to figure out what was going on, but it was impossible to determine what units were being used in the program. Finally, I gave up and put the following comment in the program:

/******************************************************** 
 * Note: I have no idea what the input units are, nor   * 
 *      do I have any idea what the output units are,   * 
 *      but I have discovered that if I divide by 3     * 
 *      the plots look about the right size.            * 
 ********************************************************/

One problem many beginning programmers have is that they describe the code, not the variable. For example:

int top_limit;     // Top limit is an integer [bad comment]

It’s obvious from the code that top_limit is an integer. I want to know what top_limit is. Tell me.

int top_limit;    // Number of items we can load before losing data

You should take every opportunity to make sure your program is clear and easy to understand. Do not be clever. Cleverness makes for unreadable and unmaintainable programs. Programs, by their nature, are extremely complex. Anything you can to do to cut down on this complexity will make your programs better. Consider the following code, written by a very clever programmer.

while ('
' != *p++ = *q++);

It is almost impossible for the reader to tell at a glance what this mess does. Properly written this would appear as shown in Example 3-2:

while (true) { 
    *destination_ptr = *source_ptr; 
    ++destination_ptr; 
    ++source_ptr; 
    if (*(destination_ptr-1) == '
')  
        break;  // exit the loop if done 
}

Although the second version is longer, it is much clearer and easier to understand. Even a novice programmer who does not know C++ well can tell that this program has something to do with moving data from a source to a destination.

The computer doesn’t care which version is used. A good compiler will generate the same machine code for both versions. It is the programmer who benefits from the verbose code.

Names can contain both uppercase and lowercase letters. In this book we use all lowercase names for variables (e.g., source_ptr, current_index). All uppercase is reserved for constants (e.g., MAX_ITEMS, SCREEN_WIDTH). This convention is the classic convention followed by most C and C++ programs.

Many newer programs use mixed-case names (e.g., RecordsInFile). Sometimes they use the capitalization of the first letter to indicate information about the variable. For example, recordsInFile might be used to denote a local variable while RecordsInFile would denote a global variable. (See Chapter 9 for information about local and global variables.) You should be careful when making up rules for your variables because the more complex the rules, the more likely someone will violate them or get confused.

One additional note on variable names: please use whole words. The problem with abbreviations is that there are too many different ways of abbreviating the same word. This is especially true when programmers think that to abbreviate a word, you write down the word and then cross out random letters. I’ve seen “Ground Point” named gp, ground_pt, gnd_pt, g_pnt, and many others. On the other hand, there’s only one full spelling: ground_point.

Also, I work for a company which has people from 62 different countries working together to produce code. The non-English speakers have real difficulty looking up the more unusual abbreviations. Words in the dictionary make things much easier to understand for people who have to deal with the twin complexities of English and C++.

Which naming convention you use is up to you. It is more a matter of religion than of style. However, using a consistent naming style is extremely important. In this book we have chosen the first style—lowercase variable names and uppercase constants—and we use it throughout the book. (Note that this convention is growing less common as old-style #define constants are being replaced with new-style const ones.)

Computer scientists have devised many programming styles. These include structured programming, top-down programming, and goto -less programming. Each of these styles has its own following or cult. I use the term “religion” because people are taught to follow the rules without knowing the reasons behind them. For example, followers of the goto-less cult will never use a goto statement, even when it is natural to do so.

The rules presented in this book are the result of years of programming experience. I have discovered that by following these rules, I can create better programs. You do not have to follow them blindly. If you find a better system, by all means use it. (If it really works, drop me a line. I’d like to use it, too.)

To make programs easier to understand, most programmers indent their programs. The general rule for a C++ program is to indent one level for each new block or conditional. In Example 3-2 there are three levels of logic, each with its own indentation level. The while statement is outermost. The statements inside the while are at the next level. The statement inside the if (break) is at the innermost level.

There are two styles of indentation, and a vast religious war is being waged in the programming community as to which is better. The first is the short form:

while (! done) { 
    std::cout << "Processing
"; 
    next_entry(  ); 
} 

if (total <= 0) { 
    std::cout << "You owe nothing
"; 
    total = 0; 
} else { 
    std::cout << "You owe " << total << " dollars
"; 
    all_totals = all_totals + total; 
}

In this case, most of the curly braces are put on the same line as the statements. The other style puts the curly braces on lines by themselves:

while (! done)  
{ 
    std::cout << "Processing
"; 
    next_entry(  ); 
} 

if (total <= 0)  
{ 
   std::cout << "You owe nothing
"; 
   total = 0; 
} 
else  
{ 
   std::cout << "You owe " << total << " dollars
"; 
   all_totals = all_totals + total; 
}

Both formats are commonly used. You should use the format you feel most comfortable with. This book uses the short form. (It saves paper.)

The amount of indentation is left to the programmer. Two, four, and eight spaces are common. Studies have shown that a four-space indent makes the most readable code. You can choose any indent size as long as you are consistent.

:set cindent
:set sw=4

A program should read like a technical paper, organized into sections and paragraphs. Procedures form a natural section boundary. You should organize your code into paragraphs, beginning a paragraph with a topic sentence comment and separating it from other paragraphs with a blank line. For example:

// poor programming practice
temp = box_x1; 
box_x1 = box_x2; 
box_x2 = temp; 
temp = box_y1; 
box_y1 = box_y2; 
box_y2 = temp;

A better version would be:

/* 
 * Swap the two corners  
 */ 

/* Swap X coordinate */ 
temp = box_x1; 
box_x1 = box_x2; 
box_x2 = temp; 

/* Swap Y coordinate */ 
temp = box_y1; 
box_y1 = box_y2; 
box_y2 = temp;

Your program should be simple. Here are some general rules of thumb:

Good style is only one element in creating a high-quality program. Consistency is also a factor. This book is organized with the table of contents at the front and the index at the back. Almost every book printed has a similar organization. This consistency makes it easy to look up a word in the index or find a chapter title in the table of contents.

Unfortunately, the programming community has developed a variety of coding styles. Each has its own advantages and disadvantages. The trick to efficient programming in a group is to pick one style and use it consistently. That way you can avoid the problems and confusion that arise when programs written in different styles are combined.

Good style is nice, but consistency is better.

In this chapter we have touched only the basics of style. Later chapters expand on this base, adding new stylistic elements as you learn new elements of the language.

For a more complete discussion of style, the online book C Elements of Style is available from http://www.oualline.com.

A program should be concise and easy to read. It must serve as a set of computer instructions, but also as a reference work describing the algorithms and data used inside it. Everything should be documented with comments. Comments serve two purposes: they describe your program to any maintenance programmer who has to fix it, and they help you remember what you did.

Class discussion 1: Create a style sheet for class assignments. Discuss what comments should go into the programs and why.

Class discussion 2: Analyze the style of an existing program. Is the program written in a manner that is clear and easy to understand? What can be done to improve the style of the program?