Book Cover

Introduction to Scientific Programming
Computational Problem Solving Using:
Maple and C
Mathematica and C

Author:
Joseph L. Zachary
Online Resources:
Maple/C Version
Mathematica/C Version

Formatting C Programs Tutorial

In this turorial we will look at the importance of writing programs that are well-commented, use meaningful variable names, and are well-formatted. We will also look at some of the ways in which Emacs will help you with formatting.

Most students wouldn't hand in a term paper written with sloppy handwriting on paper ripped out of a composition book. But many beginning programmers hand in programs that, even though they may work, are hard to read.

Making your program easier for others to read and understand will inevitably make it easier for you to read and understand it. It will increase your programming productivity and save you a lot of time in the long run.

Comments

All of the programs that we give you contain the kinds of comments that we expect you to use in your programs. But just to be sure that you understand, take a look at comments.c.

Each file should contain a comment header with the following information:

  1. A short description of the program that the file contains.
  2. The name of the creator and creation date of the program.
  3. A history of when modifications were made, who made them, and what the modifications were. Again, especially in large projects with more than one programmer, this helps let the reader know who might know more about the program.

There should also be a header before every function explaining what the function does.

It is not usually necessary to use comments to explain how a function works. Given a well-written function and a comment explaining what the function does, it is usually not too difficult for a reader to figure out how it is done. There are exceptions, of course.

Variable Names

Take a look at bad.c. What's bad about it?

Click here for the answer

Here is some simple but valuable advice: use variable names that reflect the purpose of the variable in the program. What would be better names for ``sheba'' and ``riffraff'' in this program?

Click here for the answer

Indentation

Look at the program indent.c. There are two things wrong with it. Look at it for no more than a minute and try to figure out what is wrong, besides the fact that it is completely unindented.

Did you find the problems? How long did it take? In case you didn't (or even if you did) try asking Emacs to indent the program. To do that, use the mouse to select (highlight) the entire program. Then pull down the Compile menu and select the Indent Selection option. What happens?

Click here for the answer

Fix the problem and then reindent the program. What happens?

Click here for the answer

Fix the problem and indent once more. The program should be properly indented.

You have probably noticed that Emacs automatically indents programs for you as you write them. You should get into the habit of watching how Emacs indents your program. As you get used to how the indentation is done, you will begin to notice problems with your programs as you are writing them.

If you go into the middle of a function and begin changing it, Emacs' indentation can be thrown off. In that case, you should use the Indent Selection command to reindent the function.

Balancing Parentheses

A common mistake when typing in programs is forgetting to properly balance parentheses, braces, and square brackets. Emacs gives you some help here. What is it?

Click here for the answer

There's another helpful feature. If you put the mouse over a parenthesis, brace, or bracket and double click, the part of the program over to the matching parenthesis, brace, or bracket is highlighted.

C Mode

You should still have the program indent.c in your Emacs buffer. Use the Save Buffer As... option of the File menu to save the program under the name new-indent.c.

Now pull down the Compile menu and select the Compile This File... option. Look at the bottom of the Emacs window at the command that Emacs proposes to use to compile the file. What is wrong?

Click here for the answer

Sometimes you will be working on a C program and Emacs will not appear to recognize it as such. Perhaps it will not indent the program properly, or the Compile option is missing from the menu bar.

There are sensible reasons why Emacs is exhibiting this behavior, but it is easier to explain how to fix the problems than it is to explain why they occur. When you are having any problem like that described in this section, enter the command <Meta>x c-mode. That is, hold down the Meta key and press x, then release the Meta key and enter c-mode.

Try compiling again. This time, Emacs should use the right filename.

Online Help

Unlike Maple, C does not provide a convenient help facility for explaining the behavior of library functions. Fortunately, online help is available elsewhere.

For example, suppose that you would like to learn about the function pow. Go to a Unix Shell window and enter the command

man pow

The man stands for ``manual''. You will see an explanation of pow. To page through the explanation, hit the space key. To quit, type the q key.