*-----------------------------------------*
| Commenting and Indentation Requirements |
*-----------------------------------------*
The following three types of comments are required in each program

1. Project comment:
Located at the start of the program, this comment should give your name,
the course number and section, the project number, and the due date and time.
It should also give a general description of the project.

2. Function comments:
Located above each function, these comments should give a general description
of what the function accomplishes.

3. Section comments:
Located above each logical section of code, these comments should describe
the purpose of that particular section.

Occasionally, there is a need for an additional type of comment, a line 
comment. These comments are written when a particular line of code needs
extra explanation of its purpose (as opposed to a logical section). Do not
write redundant line comments (see DOs and DON'Ts #3 for more detail). 


*-------------------------------------------*
| Commenting and Indentation DOs and DON'Ts |
*-------------------------------------------*

1. DO align comments with the code to which they refer. 

2. DON'T use /* Local Definitions */ and /* Statements */ comments aligned in 
column one as described in the book. 

3. DO write comments which explain the purpose of a section of code. 
Comments are meant to increase readability of code, therefore the comments 
should be meaningful and describe purpose. They should not be redundant and 
describe exactly what happens in a particular line. 
For example, the comment for the following statement is redundant.
   printf("\nThe result is %d.", result);   /* print the result */
There may be times, however, when a line comment is necessary to explain the 
purpose of a particular line of code - but not to dissect exactly what occurs 
in the execution of the line.

4. DO indent each control level (body of function, body of if-else, body of 
loop, etc.) at least three spaces. 

5. DON'T use tabs for indentation; they differ from system to system.

6. DO separate logical sections of code with blank lines. 

7. DON'T put blank lines between comments and the code to which they refer.



- example of project comment -
/***************************************************************************
   Name: Justin Gaudry
   Course: COP 2220 000
   Description: Project 1
   Due Date/Time: January 30, 10:00 a.m.

   This program will take an integer length and width of a rectangle 
   from the user, calculate area and perimeter, and display the output 
   in unaligned statement format on the screen (vs. aligned report format).
****************************************************************************/

/* preprocessing directives */      - example of section comment     -
#include <stdio.h>                  - although not within a function -

                                    - example of function comment -
// primary function of program: main() controls obtaining input, performing
// area/perim calculations, and displaying output back to user 
int main(void)
{
   int length, width;
   int area, perim;

   // obtain input from user      - example of section comment -
   printf("\nEnter the length of the rectangle: ");
   scanf("%d", &length);
   printf("\nEnter the width of the rectangle: ");
   scanf("%d", &width);

   // perform calculations        - example of section comment -
   area = length * width;
   perim = 2 * (length + width);

   // display output              - example of section comment -
   printf("\nThe area of a %d x %d rectangle is %d.", 
          length, width, area);
   printf("\nThe perimeter of a %d x %d rectangle is %d.", 
          length, width, perim);

   // format and finish           - example of section comment -
   printf("\n\n");
   return 0;
}

Notice the logical sections separated by blank lines and headed with 
section comments. They give a breakdown of the program: obtain input, 
perform calculations, display output, format and finish.