(Latest Revision -- 02/10/00)

GENERAL INSTRUCTIONS
FOR SUBMITTING 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.

TO BE SUBMITTED ELECTRONICALLY:

You are required to turn in two items: 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 the two items listed above as a separate e-mail message. Furnish a suitable subject line with your messages. Address mail to john@ishi.csustan.edu.

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 version of the program must also meet the criteria below. The criteria with their relative weights are: 
40      Minimally acceptable program as above.
20      Good design, including good algorithms.
20      Adequate testing, especially the testing of
        data boundaries and special cases.
20      Good form, including documentation, and readability.
DOCUMENTATION:

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

Each function (this includes "main") must have a header comment containing a short description of what the function is supposed to accomplish. (In the case of a function stub, the header comment tells what the function will do when it is finished.)

In order to competently tell what the function 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 function to be assured of executing correctly, and what postconditions will be true when execution of the function ends.

The header of a function must contain the names of the important variables, and data structures it contains. It must explain what the function 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 function "main" 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 any function besides "main" 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, 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 function "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.

GOOD FORM:

You must use a readable, logical, and coherent set of style and formatting rules. For some tips on this topic, see pp 61-62 in Chapter Two of "A Computer Science Tapestry."

STRUCTURED PROGRAMMING AND MODULARITY:

I expect you to stick to the "structured approach" in programming. This means using top-down design, modular code, information hiding, and "orderly flow of control".