3. How Do I Know What’s Happening?
Through Comments
In This Chapter
Your computer must be able to understand your programs. Because the computer is a dumb machine, you must be careful to spell C commands exactly right and type them in the same order you want them executed. However, people also read your programs. You will change your programs often, and if you write programs for a company, the company’s needs will change over time. You must ensure that your programs are understandable to people as well as to computers. Therefore, you should document your programs by explaining what they do.
Commenting on Your Code
Throughout a C program, you should add comments. Comments are messages scattered throughout your programs that explain what’s going on. If you write a program to calculate payroll, the program’s comments explain the gross pay calculations, state tax calculations, federal tax calculations, social security calculations, and all the other calculations that are going on.
Note
If you write the program and only you will use it, you don’t really need comments, right? Well, not exactly. C is a cryptic programming language. Even if you write the program, you aren’t always able to follow it later.
Clue
Add comments as you write your programs. Get in the habit now, because programmers rarely go back and add comments later. When they must make a change later, programmers often lament about their program’s lack of comments.
There is another advantage to commenting as you write the program instead of waiting until after you finish. While writing programs, you often refer back to statements you wrote earlier in the process. Instead of reinterpreting C code you’ve already written, you can scan through your comments, finding sections of code that you need faster. If you didn’t comment, you would have to decipher your C code every time you looked through a piece of it.
Program maintenance is the process of changing a program, over time, to fix hidden bugs and to adapt the program to a changing environment. If you write a payroll, program for a company, that company could eventually change the way it does payroll, and you (or another programmer) will have to modify the payroll, program to conform to the company’s new payroll procedures. Commenting speeds program maintenance. With comments, you or another programmer can quickly scan through a program listing finding the areas that need changing.
Comments are not C commands. C ignores every comment in your program. Comments are for people, and the programming statements residing between the comments are for the computer. (See Figure 3.1.)
Figure 3.1. Comments are for people, and C programming statements are for the computer.
Consider the following C statement:
return ((s1 < s2) ? s1 : s2);
You don’t know C yet, but even if you did, this statement takes some study to figure out. Isn’t this better:
return ((s1 < s2) ? s1 : s2); /* Gets the smaller of 2 values */
The next section explains the syntax of comments, but for now, you can see that the message between the /* and the */ is a comment.
The closer a comment is to spoken language and the further a comment is from C code, the better the comment is. Don’t write a comment just for the sake of commenting. The following statement’s comment is useless:
printf("Payroll"); /* Prints the word "Payroll" */
Warning
You don’t know C yet, and you still don’t need the preceding line’s comment! Redundant comments are a waste of your time, and they don’t add anything to programs. Add comments to explain what is going on to people (including yourself) who might need to read your program.
Specifying Comments
C comments begin with /* and end with */. Comments can span several lines in a program, and they can go just about anywhere in a program. All of the following lines contain C comments:
/* This is a comment that happens to span two lines
before coming to an end */
/* This is a single-line comment */
for (i = 0; i < 25; i++) /* Counts from 0 to 25 */
Note
Notice that comments can go on lines by themselves or before or after programming statements. The choice of placement depends on the length of the comment and the amount of code the comment describes.
The Blackjack program in Appendix B contains all kinds of comments. By reading through the comments in that program, you can get an idea of what the program does without ever looking at the C code itself.
Don’t comment every line. Usually only every few lines need comments. Many programmers like to place a multiline comment before a section of code and then insert a few smaller comments on lines that need them. Here is a complete program with different kinds of comments:
Many companies require that their programmers embed their own names in comments at the top of programs they write. If changes need to be made to the program later, the original programmer can be found to help out. It’s also a good idea to include the filename that you use to save the program on disk at the beginning of a program so that you can find a program on disk when you run across a printed listing.
Note
This book might comment too much in some places, especially in the beginning chapters. You are so unfamiliar with C that every little bit of explanation helps.
For testing purposes, you might find it useful to comment out a section of code by putting a /* and */ around it. By doing this, you cause C to ignore that section of code, and you can concentrate on the piece of code you’re working on. Do not, however, comment out a section of code that already contains comments because you cannot embed one comment within another. The first */ that C runs across triggers the end of the comment you started. When C finds the next */ without a beginning /*, you get an error.
White Space
White space is the collection of spaces and blank lines you find in many programs. In a way, white space is just as important in making your programs more readable than comments are. People need white space when looking through C programs instead of a program that runs together too much. Consider the following program:
This program is a perfectly good C program—to a C compiler, but not to a person looking at the program. Although the code is simple and it doesn’t take a lot of effort to figure out what is going on, the following program, even though it has no comments, is much easier to decipher:
This program listing is identical to the previous program except that this one includes comments whereas the previous one did not. The physical length of a program does not determine readability; the amount of whitespace does. (Of course, a few comments would improve this program too, but the purpose of this exercise is to show you the difference between no white space and good white space.)
Note
You might be wondering why the first line of the squeezed program, the one with the #include, did not contain code after the closing angle brace. After all, it would seem that the point of unreadable code would be made even more strongly if the #include contained trailing code. The author (that’s me) tried to do just that! Many, if not all, C compilers refuse to allow code after a #include (or any other statement that begins with a pound sign (#)). Some C compilers even refuse to allow comments at the end of such lines, although many of today’s C compilers do let you put comments there.
The Future of Comments
Many of today’s C compilers support another kind of comment that was originally developed for C++ programs. This new kind of comment is not approved for use by ANSI C, but might be someday soon because it’s so popular. The new style of comment begins with two slashes (//) and ends only at the end of the line.
Here is an example of the new style of comment:
Because the new style of comment isn’t sanctioned by the ANSI C committee, this book doesn’t use it again. However, you should become familiar with this style because it’s easier to use than /* and */, and many C programmers are beginning to use it.
Rewards
• The three rules of programming are comment, comment, comment. Use comments abundantly.
• When you want to comment, begin with /*. End the comment with */.
• If you want to use the new style of comment, begin the comment with //. This kind of comment, however, isn’t yet approved by ANSI C.
Pitfalls
• Don’t use redundant comments. Worthless comments aren’t helpful, and they waste valuable programming time.
• Don’t nest one comment inside another. If you want to comment out a section of your program, you must make sure that the section doesn’t contain other comments.
• Don’t write programs that have little white space. Put as much indention and as many extra lines throughout a program as needed to group lines that go together. As you learn more about the C language, you’ll learn where white space adds to a program’s readability.
In Review
You must add comments to your programs, not for computers, but for people. Although C programs can be cryptic, comments eliminate lots of confusion. A comment is just a message that describes what’s going on in the C code. Anything between the /* and */ is a C comment. C ignores all comments because it knows that comments are for people.
In addition to comments, add lots of white space to your programs to make your programs more readable. If a program is crunched together without blank lines and helpful indention, you’ll feel as if you’re reading an entire book with one long paragraph when you go back and study and modify the code later. Easing program maintenance through comments and ample white space saves you time and energy if you change the program later.
Code Example
Here are two lines without comments:
scanf(" %d", &a);
yrs = (a >= 21) ? 0 : 21 - a;
Here are the same two lines with comments:
Code Analysis
As you can see from these lines, it’s not always obvious what goes on in C programs. Comments explain in plain, spoken language exactly what’s going on with the code. Not every line in every C program needs a comment, but many do to clarify what’s happening.