CODING STANDARDS
  ----------------

All of the following standards are subject to grading. Failure to conform to standards 
may result in points lost on an assignment.

The purpose of these requirements is readable, easy-to-understand (and grade)
code. If a reasonably proficient coder would have difficulty understanding your
code, it's readability must be improved.

I. Program Organization

   General Format
   --------------

   The format that every file should follow is:

   (a) block comment including short description, developer name and email
   (b) #include and other preprocessor statements (if any)
   (c) function definitions
   (d) the main() function, if present, comes last

   Note that not all these items will be part of every file;  however, 
   EVERY file should include item (a).  The rest of the items should be used
   be used in the order given, though I allow (d) and (c) to be reversed, in
   which case the main() function must be preceded by function signatures for the rest.

   Using .h and .c files with ADTs
   -------------------------------

   Each ADT definition (typically struct + function signatures for operations)
   should be placed in a separate header file, included (using #include) in each
   module which uses that definition. In general, no procedural code should appear 
   in this file (exceptions include macros and one-line implementations of simple
   functions).

   Each ADT function should be implemented in a separately compiled C program file.

   Use small functions
   -------------------

   Keep functions as small as possible. In general, code for a function should be 
   limited to no more than what will fit on one screen.

II. COMMENTS

   Use a block comment at the beginning of each file
   -------------------------------------------------

   Each file should have a comment block starting on the first line of the file giving
   the filename, the name and email address of the programmer, a description of the
   contents of the file, and any other pertinent information.

   Use a short block comment before each function
   ----------------------------------------------

   Each function should be preceded by a comment describing the function, its parameters  
   and return value (in the form of pre- and post-conditions), side effects (such as the
   use of [shudder!] global variables), and any known bugs or limitations.

   Minimize use of inline comments
   -------------------------------

   Every major section of code needs an inline comment for clarification, but
   these should be used sparingly.

III. INDENTATION

   Indent consistently using a reasonable style
   --------------------------------------------

   Each control construct (fuction definition, selection/iteration construct, etc.)
   should define a new indentation level. There are two major ways of handling
   braces:

   The First Way:

      Line up left braces with right braces.  As braces are hard to see, you will find
      it much easier to detect mismatched braces this way.

      Example:

      for (i = 0; i < 10; i++)
      {
          a[i] = 7 * i;
          b[i] = i;
      }

   The Second Way:

      Place left braces at the end of the line where the block of statements starts.
      This saves a few lines but you may pay for it by spending more time trying to locate
      mismatched braces (though modern editors typically help with this).

      Example:

      for (i = 0; i < 10; i ++) {
          a[i] = 7 * i;
          b[i] = i;
      }

   Don't be chintzy with indentation
   ---------------------------------

   Use at least 3 spaces for each indentation level


IV. NAMING CONVENTIONS
 
   Use readable English names
   --------------------------

   Constants, variables, and functions should be given names that are good 
   meaningful English.  Keep names like I, J, and Z to a minimum (okay for 
   for loop variables, for example).  When names are stated in the program
   assignment handout, they MUST be used.

   Use abbreviations sparingly
   ---------------------------

   A few common abbreviations (such as "num" for "number") are common enough
   that they won't be misunderstood.  It is a good idea to comment variables 
   so their meanings are clear. If a variable is redefined, an explanatory 
   comment is essential.

V.  GENERAL

   File naming
   -----------

   Files should be named according to the program assignment handout. Any special 
   information needed to compile/run the program should be in a file called README
   or README.txt.

   Miscellaneous
   -------------

   At this level, all programs should compile and have been tested. There should
   be no infinite loops, system lockups, or output that doesn't make sense. It
   is your responsibility to seek help for compilation errors or unreasonable
   output. The programs should run according to the handout requirements.

   If there is a problem with any of these, document known issues/bugs in the
   README file, what steps were attempted the correct the problem, and any ideas you
   have as to what went wrong.