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
that way.
And sometimes the "other programmers" are really ourselves some time
later.
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 */
Such
in-line
comments can be useful when describing why
a particular line of a program is there.
We, probably more often, find
block comments.
These are often designated like this:
/*
* add_stud() - add a student to a class
* Arguments:
* 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.
* Algorithm:
* 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
add_stud
and describes what the function does.
Notice that we've put a one-line description of what this function
does first.
Then we have sections that describe specific parts of the function.
Exactly what these parts are referring to will be discussed in
the
next part
.
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
add_stud
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
followed.
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
under-commenting.
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
a program.
Comments that don't add any additional information will clutter up
a program and make it harder to read.
For example:
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
why
x
is
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
Programming Course.
You may return to the
index
or
move on to
Lesson 2
.