Just a Comment on C
Our last topic for this part is one of the most important features
of C, the comment.
Comments are descriptions of the program included within the program
itself and intended for other programmers.
They are ignored by the compiler and have no effect on the execution
of the program.
Comments are vital parts of programs because they make it possible for
other programmers to understand what we've done and why we've done it
And sometimes the "other programmers" are really ourselves some time
Many programmers have had the experience of looking at a program they
wrote a couple of years earlier and not being able to remember what
they did or why.
Comments begin with the sequence
and end with
For example we might find such a line in a C program:
num_stud = num_stud + 1; /* A student has been added */
comments can be useful when describing why
a particular line of a program is there.
We, probably more often, find
These are often designated like this:
* add_stud() - add a student to a class
* stud - ID number of the student being added
* class - designator of the class to which the student is
* being added
* Return Value:
* the new number of students in the class. If that is the
* same as the old number of students, then the student was
* not added.
* 1. See if the class is at or over it's limit
* 2. If so, then return the current number of students
* 3. Otherwise, check to see if the student is already
* in the class. If so return the current number
* of students.
* 4. Otherwise, insert the student into the class list
* in alphabetical order based on the last name (and
* first name if the last names are the same.)
* 5. Return 1 + the old number of students in the class.
This block of comments will preceed a function called
and describes what the function does.
Notice that we've put a one-line description of what this function
Then we have sections that describe specific parts of the function.
Exactly what these parts are referring to will be discussed in
We normally have one such block at the beginning of each function
in a program and one at the beginning of the whole program.
The one at the beginning of a program including
might look like:
* Student Scheduler
* by Brian L. Stuart
* Started: 6/15/94, Last Revision: 8/25/95
* This program provides a basic student scheduling system.
and would go on to describe the basic purpose and organization
of the program.
It's also helpful at this point in the comments to describe any
limitations or assumptions that the program makes.
Finally, we wrap up with a few dos and don'ts about commenting.
Do describe every decision you make in the programming process.
Your program may only work correctly if one set of restrictions is
But later another programmer may come along not knowing about your
restrictions and add features that violate those restrictions.
Not informing that programmer of what you know will cause undue
delays in debugging.
Don't over- or under-comment.
The biggest problem (for students and professionals alike) is
Most programmers are so busy writing code, they think of commenting
as an onerous task that is best put off till last.
Then there's no time to comment well.
We've all done it.
Having said that, you might think it's not possible to over-comment
Comments that don't add any additional information will clutter up
a program and make it harder to read.
x = 5; /* Set x to 5 */
doesn't tell anyone who knows C anything they didn't already know
from looking at the statement itself.
Now it might be useful to tell the reader
being set to 5.
But that it is being set will be clear enough to anyone who knows
as much about C as you do.
Do clearly explain any special techniques you use that might
not be known to most programmers even if it seems obvious to you.
Do cite your sources.
To include someone else's code without giving credit is just as much
plagiarism as failing to cite sources in a paper you write.
While it's probably not plagiarism to fail to cite where you got
the algorithm for some function, it's helpful to cite it anyway.
That way the reader knows where to look for further explanation
and to see if you introduced any bugs in coding it.
Congratulations, you have finished Part 1 of the Experimental C
You may return to the
move on to