- 3 - How Do I Know What's Happening? Through Comments

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.

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" */

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 */

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:

/* Written by: Perilous Perry, finished on April 9, 1492 */
/* Filename: AVG.C */
/* Computes the average of three class grades */
#include <stdio.h>
main()
{
  float gr1, gr2, gr3;  /* Variables to hold grades */
  float avg;            /* Variable to hold average */
  /* Asks for each student's grade */
  printf("What grade did the first student get? ");
  scanf(" %f", &gr1);
  printf("What grade did the second student get? ");
  scanf(" %f", &gr2);
  printf("What grade did the third student get? ");
  scanf(" %f", &gr3);
  avg = (gr1 + gr2 + gr3) / 3.0;  /* Computes average */
  printf("\nThe student average is %.2f", avg);
  return 0;  /* Goes back to DOS */
}

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.

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:

#include <stdio.h>
main(){float s,t;printf("How much do you make? ");scanf(" %f",
&s);t=.33*s;printf("You owe %.2f in taxes.",t);return 0;}

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:

#include <stdio.h>
main()
  {
    float s, t;
    printf("How much do you make? ");
    scanf(" %f", &s);
    t = .33 * s;
    printf("You owe %.2f in taxes.", t);
    return 0;
}

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.)

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:

// Short program!
#include <stdio.h>
main()
{
  printf("Looking good!");  // A message
  return 0;
}

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.

• 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:

scanf(" %d", &a);  /* Gets the user's age */
yrs = (a >= 21) ? 0 : 21 - a;  /* Calculates the number of */
                               /* years until adulthood */

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.

For beginning programmers, this updated edition answers all C programming questions. This bestseller talks to readers at their level, explaining every aspect of how to get started and learn the C language quickly. Readers also find out where to learn more about C. This book includes tear-out reference card of C functions and statements, a hierarchy chart, and other valuable information. It uses special icons, notes, clues, warnings, and rewards to make understanding easier. And the clear and friendly style presumes no programming knowledge.

Part 1 First Steps with C

Chapter 1 - What Is C Programming?

Rewarding and Fun
What Is a Program?
What You Need to Write C Programs
The Programming Process
Using C

Chapter 2 - How Do I Get Started in C?

With the main() Function
Getting a Glimpse
The main() Function
Kinds of Data
In Review

Chapter 3 - How Do I Know What's Happening?

Through Comments
Commenting on Your Code
Specifying Comments
White Space
The Future of Comments
In Review

Chapter 4 - Can I See Results?

With printf()
What printf() Does
The Format of printf()
Printing Strings
Escape Sequences
Conversion Characters
In Review

Chapter 5 - How Do I Store Stuff?

Using Variables
Kinds of Variables
Naming Variables
Defining Variables
Storing Data in Variables
In Review

Chapter 6 - Can C Store Words?

In Character Arrays
"I Am the String Terminator!"
The Length of Strings
Character Arrays: Lists of Characters
Initializing Strings
In Review

Chapter 7 - What Do #include and #define Mean?

They're Preprocessor Directives
Including Files
Where Do I Put #include Directives?
Defining Constants
In Review

Chapter 8 - Can I Ask the User Questions?

With scanf()
Looking at scanf()
Prompting for scanf()
Problems with scanf()
In Review

Chapter 9 - How Does C Do Math?

With Operators
The Basics
Order of Operators
Break the Rules with Parentheses
Assignments Everywhere
In Review

Part 2 The Operating Room

Chapter 10 - What Else Can I Do with Expressions?

Combine Operators and Give Typecasts
Compound Assignment
Watch That Order!
Typecasting: Hollywood Could Take Lessons from C
In Review

Chapter 11 - Can I Compare Two Values?

With Relational Operators
Testing Data
Using if
Otherwise...: Using else
In Review

Chapter 12 - How Do I Test Several Things at Once?

With Logical Operators
Getting Logical
The Order of Logical Operators
In Review

Chapter 13 - Are There More Operators?

Additional C Operators
Goodbye if-else; Hello Conditional
The Small-Change Operators: ++ and --
Sizing Up the Situation
In Review

Part 3 Keeping Control

Chapter 14 - How Can I Do the Same Stuff Over and Over?

With while and do-while Loops
while We Repeat
Using while
Using do-while
In Review

Chapter 15 - Are There Other Loops?

The for Loop
for Repeat's Sake!
Working with for
In Review

Chapter 16 - What if I Want to Stop in the Middle of a Loop?

Use break and continue
Take a break
Let's continue Working
In Review

Chapter 17 - How Can I Test Lots of Values?

With the switch Statement
Making the switch
break and switch
Efficiency Considerations
In Review

Chapter 18 - How Else Can I Control Input and Output?

With Built-In I/O Functions
putchar() and getchar()
The Newline Consideration
A Little Faster: getch()
In Review

Chapter 19 - Can You Tell Me More About Strings?

C's Built-In Character and String Functions
Character-Testing Functions
Is the Case Correct?
Case-Changing Functions
String Functions
In Review

Chapter 20 - Can C Do My Math Homework?

The Built-In Numeric Functions Show You
Practicing Your Math
Doing More Conversions
Getting Into Trig and Other Really Hard Stuff
Getting Random
In Review

Part 4 C Programs and Lots of Data

Chapter 21 - How Does C Work with Lists?

Using Arrays
Reviewing Arrays
Putting Values in Arrays
We're Not Done Yet
In Review

Chapter 22 - How Can I Search for Data?

Step Through Arrays
Filling Arrays
Finders Keepers
In Review
Chapter 23 - How Can I Arrange and Alphabetize?
The Bubble Sort Does the Trick
Putting Your House in Order: Sorting
Faster Searches
In Review

Chapter 24 - What's the Point?

Using Pointers, You'll Find Out
Memory Addresses
Defining Pointer Variables
Using the Dereferencing *
In Review

Chapter 25 - How Are Arrays and Pointers Different?

They're the Same Thing in C
Array Names Are Pointers
Getting Down in the List
Characters and Pointers
Be Careful with Lengths
Arrays of Pointers
In Review

Chapter 26 - Where's More Memory?

Try the Heap
Thinking of the Heap
But WHY Do I Need the Heap?
How Do I Allocate the Heap?
If There's Not Enough Heap Memory
Freeing Heap Memory
Multiple Allocations
In Review

Chapter 27 - How Do I Store Lots of Data?

With Structures
Defining a Structure
Putting Data in Structure Variables
In Review

Part 5 Form Follows Functions

Chapter 28 - Can My Programs Save Stuff on Disk?

With Sequential Files
Disk Files
Opening a File
Using Sequential Files
In Review

Chapter 29 - Is There Another Way to Save Files?

Use Random Files
Opening Random Files
Moving Around in a File
In Review

Chapter 30 - How Can I Better Organize My Programs?

Using Functions
Form Follows C Functions
Local or Global?
In Review

Chapter 31 - How Do Functions Share Data?

By Passing Variables
Passing Arguments
Methods of Passing Arguments
In Review

Chapter 32 - How Can I Perfect My Functions?

Using Return Values and Prototypes
Returning Values
The Return Data Type
One Last Step: Prototype
Wrapping Things Up
In Review

Chapter A - Where Do I Go from Here?
Chapter B - Playing Around with C Blackjack
Chapter C - The ASCII Table

Index