Tips on Comments

Documenting code

It is important that all code you write is documented. In the "real world," documentation communicates the purpose and the function of your program to other people. In this class, documentation will also account for anywhere from 10 to 30% of the grade on a homework assignment.

Comments should tell the reader about the ALGORITHM and the OBJECTS (variables) that the algorithm manipulates. These should be explained in the context of the problem that your program solves.

Do not explain how C works (unless you're using some arcane or especially complicated construct or operator -- which you shouldn't do in this class).

Explain the significance of each variable and each step of the algorithm in solving the problem that your program addresses. BUT, by all means, be brief.

Some things to keep in mind when writing comments:

Use descriptive variable names and function names to minimize the need for comments later.
Describe the major steps of the algorithm.
Describe the objects to be manipulated (i.e.,each variable declaration).
Describe each #define used.
Describe each function call (function invocation).
Describe each function definition.
Describe exception conditions that break loops or cause function returns or program exits.

BE BRIEF YET DESCRIPTIVE.

Describing your variables:

Describe the variables when you declare them, but do not state the meaning of the declaration. The reader can see that the variables are ints and doubles. Also, use meaningful variable names: they help to self-document the code, minimizing the need for additional comments.

What your comments should tell the reader is what each variable represents in your program. In other words, briefly describe the variable in the context of the problem you are solving.

Here's an example of descriptive comments:


int 
	i; 		/* iteration counter for Newton's method */
double 
	P,		/* pressure in atm */
	T,		/* temperature in K */
	V,   		/* molar volume in liter/mole */
	residual,   	/* function value to be driven to zero */
	derivative;   	/* derivative of residual function */

Notice how each variable is given a description at the point of declaration. Also, descriptive variable names are used: e.g., 'residual' instead of 'y'. Finally, for any scientific and engineering code it is important to give the units of the variables (e.g. '/* pressure in atm */').

Here's an example of atrocious comments:


/* Declare my ints and my doubles */
	int i, j;
	double P,T,V,residual,derivative;

Anyone can see that these are ints and doubles! What needs to be explained (briefly) is their purpose (role) in solving the problem.

Avoid wordy non-informative comments:

It is common for beginners to not comment their code sufficiently and, when it is brought to their attention, to then over-comment code. Such over-commenting is usually signalled by many comments that are wordy but not informative.

This is an example of a wordy yet uninformative comment and poor variable naming:


	/* The next line scans a double from the user and stores it
	   in the memory designated by variable var. */
	scanf("%lf", &var);

This is an example of a much better comment for the above statement:


	/* Read the seed prior to generating random numbers. */
	scanf("%lf",seed);

See, we know how C works. We want to know why you are doing what you're doing in C for this problem (i.e., in the context of the problem your solving). "Read the seed" is sufficient assuming when "seed" was declared it was described correctly, e.g.
double seed; /* seed for the random number generator */

Points for Style:

It is important that another person be able to read the programs that you write.

The indentation of functions, if-elses, for-loops, and while-loops is CRITICAL in improving legibility and facilitating debugging (i.e., it is easier for YOU to figure out what's going on in your programs if you indent them).

last modified: