(1) All files which you turn in should have a comment at the top of the file which states your name, user id, class (15-211), section, and due date. This comment must also give a simple, general description of the purpose of the file.
(2) Virtually all subroutines need to have a comment describing the purpose of the subroutine. This comment should say what the routine expects in its input and what the result of executing the routine will be. Only if a procedure is extremely simple and its purpose obvious may this comment be omitted. In most cases this comment need not be long, but for some routines you may want to include a brief description of the strategy the procedure uses for solving a problem. One sample format for these comments is as follows:
/*
* INSERTNAME:The given "list" is assumed to be in sorted (alphabetical)
* order. InsertName traverses the "list" and inserts "name" into the
* appropriate place in the list using the insertion sort algorithm
* EVEN if name is already there. (In that case there will be now
* be two copies of "name".) The routine creates new storage to hold
* "name". Returns 0 if successful and -1 if it can't allocate storage.
*/
int InsertName(Llist list, char *name)
{
...
...
}
(3) Any portion of code which uses a strange algorithm, or is otherwise non-obvious, requires a brief comment describing that code. This may take the form of either an inline comment (i.e. where the ``//'' comment form is used at the end of a line) or as a seperate line or two of description.
(4) It is often useful at the beginning of large loops to specify what is guaranteed to be true at the start of each iteration through the loop. This is also important to help YOU understand why YOUR code is working properly.
Hints: You have to determine the appropriate places for comments. Comments should make any portion of your program which may need clarification understandable to others and to yourself (you may not remember what something was for a week after you wrote it).