(Latest Revision -- 08/29/2015)

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

FORM OF THE ASSIGNMENT:

Sometimes I will give you part of a program and ask you to add to it.

In other cases, I will ask you to write an entire program "from scratch."

If you are writing a large program from scratch, I may require you to turn in separate levels of the 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:

When you turn in a programming assignment, you must send me: 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 running the Terminal application and logged into a CS Lab Mac ). 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).

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: Your program has to work. That means it has to compile correctly, run according to specifications, and give correct results. The exact scoring methods I use may vary from assignment to assignment. Generally a program that works will receive at least 40-50 percent of full credit.

For full credit, each version of the program must also meet the following criteria: You need to do a good job on all the criteria in order to receive an "A" on your program.

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 comment of a function must contain the names of the parameters of the function (if any), plus explanations of what kind of data they are supposed to contain. It must explain what the function accomplishes with these objects.

For example if it is a function that inputs an array that is assumed to contain a list be sorted, then your header comment has to identify the parameter that is supposed to be the list. Also the header comment should say whether the list will be sorted in ascending or descending order, and whether it will sort the list in place, or somehow return a second copy of the list that is the sorted version. The idea is to tell enough about the function so that people will be able to figure out how to use the function based on your information.

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),

The first step towards wisdom is calling things by their right names.
- Anonymous Chinese Proverb

All names of constants, types, variables, functions, etc. must be "self-documenting" and "self-describing." For example, you should call a variable a name such as "total" if it is used to store a total. Call a function a name like "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 may not 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 the statement does. The statement

Sum = 0 ;

alone tells us just as much.

GOOD FORM:

You must use a readable, logical, and coherent set of style and formatting rules.

There must be no tab characters in your program and you must make each line in your program less than 79 characters in width, including white space and comments.

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".