/********************************************************* *Programmer: * *Program #: * *Lab Section: * *Date: * *Description: * *********************************************************/
Fill in each section as appropriate. The "Description" section should contain a brief, plain English description of the purpose of the program.
/*********************Function Name********************** *Description: * *Implementation: * *Interface: * *Callees: * *Comments: * *********************************************************/
The "Description" is a brief, plain English description of the task that the function performs. The "Implementation" gives a high-level view of the algorithm used to perform the task. This may be in plain English or pseudo-code. The "Interface" section specifies the nature of the inputs (parameters) and outputs of the function. The "Callees" section lists the functions that the current functions calls, including any library functions. If the function calls subroutines in other files, this section must specify the file in which a called subroutine is located. The "Comments" section is in some ways the most important part of the header comment block. In this section you must state any preconditions, or assumptions that must be true before the function is called in order to guarantee that it will work correctly. You must also state the postconditions; those things that will be true once the function has executed. You should also state here any side-effects that the function produces, such as changes to global variables or input from the user or from a file or output to the screen or to a file.
Section comments:
These comments occupy one or more full lines (indented to the same level
as the block they describe). They give an overview of a section (generally
comprising several statements) of a function when this section performs an
identifiable subtask within the function. Such full-line comments are
common before a loop, but may also be helpful when they precede a short
series of statements. Use blank lines before and after a section to make
it apparent where the section begins and ends.
Line comments:
These comments explain a single statement of the source code. They appear
in the right margin of the code and follow the statement they explain.
Your code will be more readable if you line them up. For example:
sum = 0; /* initialize the sum */
while (sum < 100) {
printf ("Enter a positive whole number:\n");
scanf ("%d", &i); /* read a user-entered */
/* number to add to the sum */
sum += i;
}
If you use meaningful identifiers and choose algorithms that are
inherently clear and simple, you should not need many line comments. If
you are in doubt about the clarity of your code, however, they are
appropriate and useful. Be sure that such comments are not simply a plain
English version of the C statement, but instead serve to explain why the
statement is necessary or what the statement is doing. One place you
should always include line comments is in a complicated or nested
if-then-else statement. This sort of line comment will state what must be
true at each point in the code. They are also useful just after a closing
brace when a function includes nested blocks or at the end of a function. In this latter case, use them to clarify which block the closing
brace is terminating. For example:
while (i < 10)
{
if (x > y)
{
if (y > z)
{ /* x > y > z */
... ;
} /* if (y > z) */
else
{ /* x > y && z >= y */
if (z > x)
... ;
else /* x > y && z <= x */
} /* else x > y && z >= y */
} /* if (x > y)
else /* x <= y */
... ;
++i;
} /* while (i < 10) */
Line comments are also necessary whenever you declare a variable or constant to describe the use or purpose of each such identifier.