Comp212 Grading Guideline

The following are guidelines used by your TAs and labbies to grade your programs.

Here are some specific explanations of a few items in the guide:

• Modularity and Class Organization. Do you use classes where appropriate? Are classes related to each other correctly? Proper use of public/private/protected/friend access?
• Data Abstraction (data forms reflect intent). If a group of values belong together, do you encapsulate them in a named class? (Parallel arrays should usually be avoided.) Don't use an enum or char as an int ...and if you do need to (e.g. as an array index), certainly cast it (with static_cast.
• No roundabout, confusing approaches Self explanatory. Consider the analogy of writing sentences: Sometimes a sentence gets mired in a mess, and despite all sorts of different word arrangments, nothing is satisfactory. A good editor doesn't find a way to salvage the awkward phrase; they instead re-write the sentence entirely, with the same information.
• No Repeated Code or Data (magic numbers) You want a single point of control for all actions. One minor example: if you have a field accessor, use it (including in that object's methods, unless there's good reason not to). Overloaded methods should share any common code by calling each other.
• Appropriate Commenting Comments can be about interface or implementation, and can be about individual method/field or an overview of a class or package. Don't intermix these types of comments.

  You don't need to describe the purpose of an obvious method (eg toString() or a constructor), if it is straightforward. Nor do you need to describe a method in a subclass, if it's been described in the (perhaps abstract) superclass.

• Appropriate Control Flow constructs, idioms, etc Declare local variables close to where they are used, avoid use of break if there is a straightforward alternative (there usually is), declare types as final static when possible, etc.
• Efficiencies What is a justified gross inefficiency? That's when I use a straightforward O(n³) algorithm instead of a more complicated O(n) algorithm, but I point out in comments that the code is only executed only once, and always with n<64.

  Unjustified inefficiencies are using algorithms that are big-Oh worse than needed, w/o any gain in ease of code. Example: making a growable string which grows when adding every single character, rather than successivly doubling each time growth is needed. Further examples and discussion are in Comp314 Coding Style Guidelines (pdf).

• Use helper functions is a matter of taste. The sin is to feel that you have to do everything in one big function -- that is no way to decompose a problem into simple parts! As a rule of thumb, a Scheme function shouldn't be more than ten lines or so of code, and will usually be five to six lines of code. As a general rule, if you are thinking in your head "these three lines compute the fluttershushanuff", then pay attention to the fact that your own thinking gives "fluttershushanuff" its own name; why not reflect that in your program? It's not unusual to have many small one- and two-line functions, just because they are obviously their own task.
• Appropriate use of types means (e.g.) using booleans for yes/no values, rather than using 0 and 1, or 'yep and 'nope. Later in the semester it includes using structures as needed. Overall, this point is not a big issue in Scheme.
• Magic numbers are constants hard-wired in the code that occur more than once. (Even if a constant value occurs just once, you should think about naming it.) There are a few good constants that may appear inside of code: 0, 1, true, false, and null. All others should be given a name. For instance, rather than just using "120", it should be a named constant like static final int cruiseSpeed = 120; // km per hr.
• You should test each class (often in the main for that class) as soon as you write it. Note that this means toString or paramString is one of the first methods you write for a class, so that you can print out debugging versions of your object.

  If your function returns an incorrect answer, please note this in your documentation (comments or README¹ file).

• Documentation You should contain the following information with your programs. For small programs, this might be at the top of your printout (in your main file); for most homeworks it will be in a separate file named README. You need to specify:
  • Any information for the labby, e.g. "Feature ZZZ doesn't work", or "SomeFile.java isn't really late i just forgot to copy it with cp -p".
  • Information on how to compile/install/run the program.
  • What files contain the user documentation and the code-architecture information.

  You can presume that the reader is familiar with the assignment handout, but not discussions from class. The code-architecture documentation -- which can also be in the README file -- is intended for another programmer who might be modifying your code. It has an overview of what the main classes of your program are, how they relate and interact, and the main approach taken to solve the problem. Conciseness is desired in all documentation; there is no requirement that documentation necessarily be lengthy. Clear English composition is expected.

• Late Policy Late program projects will receive a penalty of 10% of the possible points per (each part of) 24hrs late, up to 3*24hrs. Assignments late for a valid reason (such as illness, or serious family health problems) can be excused; simply see me (in advance whenever possible).
  • Note in your README, how late your assignment is, and what the published deduction is (-2% if labbies have to re-calc this).
  • Except for a 2min grace period, timestamps will be strictly interpreted.
  • Of course, fractional hours/days are rounded up.
  • The count of hours/days late includes weekends.

  Remember that your README should mention what features don't work, if you didn't have time to complete the assignment.

  Keep in mind that your labbies are grading a large number of papers, and sometimes mistakes are made. If you feel something was marked off even though it was correct, by all means check with the grader. However, if you feel that the grader was correct in taking off some points, but you feel they took off too many, try to defer to their judgement. If you feel that you've been graded overly-harshly consistently over several homeworks, first see the grader(s), If they don't agree, see a TA.

  Disclaimer: This guideline is not binding; we reserve the right to give whatever score we feel is fair.
  Guarantee: You have the right to question any score, and get an explanation of why we feel it is fair.
  See a TA or Course Instructor(s) if you are unsatisfied with a grader's explanation.

  ---

  ¹ Why the capitalized filename README? So that in a UNIX listing of files, this informational file shows up near the beginning (since capital letters are all sorted before lower-case letters in UNIX). This is also the rationale for capitalizing directory names, so that all directories precede regular files in a listing. (Unfortunately this is somewhat undermined by Java's insistence that .java files share their class's name, which is capitalized.)