Comments to the Grader: How to Grade the Programs
Here is a checklist of things you may want to consider:
I. HOW GOOD IS THE DOCUMENTATION AND CODING STYLE?
A. Machine readable documentation: the documentation should be in
the source file.
B. Identification. The identification should be part of all text
files. This identification should consist of:
Student name
Instructor
Program number
Class and section (or meeting time)
Date.
C. Statement of what program does
In our course, this will be mainly a reference to my
assignment specification.
Any bibliographical references should be clear. They are a very
important form of documentation that cost little to insert.
If there are things about the program that do not follow
the assignment, they should be clearly described. In some
cases these will be items that don't violate the statement
of the problem, but go beyond what was specified.
D. Source code for the project
Each subroutine should begin with a statement of the routine's
purpose, the significance and usage of its parameters, and
a description of any side effects. IMPORTANT: It should be
possible for another programmer to use the routine
successfully after looking at this initial documentation --
without ever looking at the body of the source code for the
routine or the documentation that goes with that source
code. This documentation at the beginning of the routine
should be regarded as a kind of user's manual; it is not
intended to show much about how the routine works.
If the routine must be used in other modules, then this
documentation should be in the header file that contains
the public declaration for the routine.
If a documentation template was provided, it should
be used for each subroutine that the student writes.
Header files (".h" files) should contain only declarations
and documentation, and only where such might be needed
elsewhere.
Names should be appropriate. Wherever practicable, constants
should be used instead of self-defining terms (for example,
PROMPT -- previously declared to be "%" -- is preferable
to "%").
Many functions -- especially system calls -- give an error
indication when they fail. The code should check such
indications in all cases, and take appropriate action.
Line comments should be used to relate specific things in the
source with the big picture provided by the
procedure/function prologs and any other high-level
documentation.
II. DID THE PROGRAM COMPILE WITHOUT WARNINGS OR ERROR MESSAGES?
In most cases, compiler warnings should cause the submission to
lose points.
If there were compile time errors (heaven forbid), the student
should say so. (If the student has any testing, diagnostics,
or commentary on the problem, s/he is encouraged to submit it.)
III. DID THE PROGRAM RUN WITHOUT SYSTEM ERROR MESSAGES?
If the program has bugs, the student should clearly show what
diagnostic work s/he has done and what theories s/he has about the
mystery. This information could be in the form of runs
and dumps. include it in the shar.proj file.
IV. DID THE PROGRAM DO WHAT THE ASSIGNMENT REQUIRED?
You'll have to read the assignment carefully and look at the
output to answer this one.
V. HOW GOOD WERE THE TEST DATA?
This part does not apply if I supplied all the test data. Note that
good test data does not mean simply lots of test data (though a large
project usually needs more testing than a small one). Good test data
should:
Test "boundary" cases,
Test all control paths,
Test any required error checking.
Testing that demonstrates capabilities that are better than required
is welcome, but it should be separate from the other tests. The
student should take note of any mysterious results, and explain them
if possible.
VI. HOW NEAT IS THE SUBMISSION?
Is the indentation consistent and readable?
Is whitespace overused (or underused)?
Are there any TAB characters? (There should be no TAB characters
in the handin.)
Feel free to mark any spelling and grammar errors you notice.
VII. ARE ALL PERIPHERAL PORTIONS OF THE ASSIGNMENT COMPLETE?
This will change from assignment to assignment. Make sure that
all the things required have been handed in.
VIII. IS THERE EVIDENCE OF COPYING OR COLLABORATION OR FAKED OUTPUT?
I treat such things as cheating.