(Last Revision: 09/03/97)

////////////////////////////////////////////////////////
GENERAL INSTRUCTIONS 
FOR SUBMITTING CS 3100 PROGRAMMING ASSIGNMENTS 
& STATEMENT OF PROGRAM GRADING POLICIES
////////////////////////////////////////////////////////

FORM OF THE ASSIGNMENT:

Typically for each programming assignment, I will require you
to turn in separate "levels" of your program:  for example, a
top-level may be due at the end of the first week, a
second-level due at the end of the second week, and a final
level due at the end of the third week.  

Each time you turn in a level of a program, it must be complete
down to the assigned depth.  It must include all the
appropriate documentation and data structures for the assigned
depth.  Portions of the program at levels not yet completed
must be represented with stubs.  (Chapter 2 of Dale and Lilly's
book "Pascal Plus Data Structures has a good description of the
use of stubs in top-down design.)

TO BE SUBMITTED ELECTRONICALLY:

For each level of a programming assignment that you turn in,
you are required to turn in two items.

1. a compilable and correctly-working copy of the program source code.     
2. a record of the set of tests that you performed on your program.  

The testing record can be conveniently made by using the
"script" command, and filtering the script file through "col
-b". (For more information on "script", type "man script" while
logged into a Sun).  While recording each test run using
"script", first cat the input file(s) (if any) for the run,
then run the program, and then cat the output file(s) (if any).

Turn in each of items 1 and 2 above as separate e-mail messages.
Furnish a suitable subject line with each message.  Address
mail to john@ishi.csustan.edu.  Please send these items as
"straight text".  Do not send them as coded enclosures, such as
PINE enclosures.  Here's an example of how to send them:

% mail -s "Prog #1" john@ishi.csustan.edu < prog1.p
% mail -s "Prog #1 script" john@ishi.csustane.edu < prog1.scr

I will, at my discretion, compile and run (on my own test
input) the programs you submit electronically.  This is a part
of my grading procedure.

POINT DISTRIBUTION:

A program must compile correctly, run according to
specifications, and give correct results.

For full credit, each level of the program must meet the
criteria below as well.  The criteria with their relative
weights are:

40      Minimally acceptable program as above.      
20      Good design, including good algorithms.      
20      Adequate testing.      
20      Good form, documentation, and readability.

DOCUMENTATION:

The proper way to create a subprogram is to first write a
header comment, then perhaps a stub, and finally the code.

Each subprogram (this includes the program itself, and every
procedure, function, or stub inside it, at any level) must have
a header comment containing a short description of what the
subprogram is supposed to accomplish.  (In the case of a
subprogram stub, the header comment tells what the subprogram
will do when it is finished.)

In order to competently tell what the subprogram does, these
"headers" must say what the inputs and outputs are, what
preconditions or assumptions, if any, have to be true in order
for the subprogram to be assured of executing correctly, and
what postconditions will be true when execution of the
subprogram ends.

The header of a subprogram must contain the names of the
important variables, data structures, and nested subprograms it
contains.  It must explain what the subprogram accomplishes
with these objects.

You must include enough detail in your headers to get the main
idea across, but no more detail than is necessary.

The beginning of the header for the main program itself must
contain your name, your username (login name), the course name,
and the date the writing of the program was completed.  Each of
these things must be clearly labeled.  The header of a
subprogram that is not the main program must give the names of
all its callers (the subprograms that call it) and the names of
all its callees (the subprograms it calls),

All names of constants, types, variables, procedures,
functions, etc.  must be "self-documenting" and
"self-describing."  For example, call a variable "total" if it
is used to store a total.  Call a procedure "PrintList" if its
job is to print a list.  If you are able to name a particular
constant, type, or variable so well that it becomes abundantly
clear from its name alone what it is used for, then it doesn't
need any further documentation.  Otherwise, you must explain
its use with "in-line" documentation next to its declaration.
I will take points off if I don't think you have documented
named objects adequately.

The decision whether to make other in-line comments is left up
to you.  However, in-line comments are only needed occasionally
in programs that have good headers, good naming conventions,
and good organization.  "Good form", which is one of the
criteria upon which your program is graded, demands that you
avoid over-commenting, as well as under-commenting.  For
example, the program line:

     Sum := 0 ; (* We initialize the value of the sum to zero *)

illustrates blatant over-commenting.  The comment inserted to
the right of the statement does not add anything to our
understanding of what is going on.  The statement

     Sum := 0 ;

tells us just as much, partly because the variable "sum" is
named so as to make it "abundantly clear" what is being done.

STRUCTURED PROGRAMMING AND MODULARITY:

You will be expected to stick to the "structured approach" in
programming.

This means using top-down design, modular procedures,
information hiding, and very few goto statements.

Keep in mind that in a good modular design, the data structures
are implemented as separate modules, each encapsulating a
representation of data and a set of operations for manipulating
the data.