Ruminations of Professor James Plank on Commenting

You will be graded on commenting. You should comment your code by blocks of comments at the beginning of your files, and before subroutines. Variables should be commented inline. You may also want to comment large blocks of code. You should not comment with a ``running commentary'' to the right of your code, because that is often useless, hard to maintain, and disconcerting. I have seen comments like the following:

  if (i == 0) {               /* If i equals zero */
    return;                   /* then return */
  } else {                    /* otherwise */
    exit(1);                  /* exit with a value of one */
The above is an extreme example, but don't let it happen to you.

Here's an example of what I would consider a well documented program:

#include < stdio.h >

/* sumnsquared.c
   Jim Plank
   August 23, 1998

   This program prompts for and reads a value n from standard
   input, and then calculates and prints the sum of squares
   from one to n.  It uses a for loop instead of using the 
   closed form expression.

  int n;                   /* The value */
  int sum;                 /* The running sum of squares */
  int i;                   /* An induction variable */

  /* Prompt for and read in a value of n */

  printf("Enter a value n: ");
  if (scanf("%d", &n) != 1) {
  /* Calculate sum for each value of i from one to n */

  sum = 0;
  for (i = 1; i <= n; i++) sum += (i*i);

  /* Print the final summation */

  printf("%d\n", sum);