3. What Does This Do? Clarifying Your Code with Comments

In This Chapter

• Commenting on your code


• Specifying comments


• Using whitespace


• Applying a second style for your 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 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, deductions, 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—you might forget why you wrote a

particular chunk of code, so a comment will help to decipher matters.

Tip

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.

Another advantage is gained when 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