ITEC325 general grading guide

general grading guide

Some common errors, marked with greek letters (lower-case). (See also, common proofreading marks.)

ι (iota): Poor indentation.
The principle is simple, across all languages: if one line is a sub-part of another, then indent it.

If you call a function, either put the entire function call on a single line, or put each arguments on it's own line.

; good
  (f a b c)
  (f a
     b
     c)

; bad
(f a b
 c)

; Horrible:
   (f a
 b c)

It is occasionally acceptable to put two arguments on the same line if (a) they're both short, and (b) they're related semantically:

; okay:
(overlay/align 'right 'center
               (rotate -90 (triangle 20 "solid" "orange"))
               (ellipse 40 20 "solid" "blue")))

For examples of good, readable code, look at any code in the class notes or in the book.

τ (tau):

Incomplete testing. You should have test cases each method you write. Test cases include actual inputs, and the expected result.

Some functions need more test cases than others.

If you include a numeric input, have a test case involving 0 (unless that makes no sense — a pizza might conceivably have diameter 0 — but not if it's guaranteed to have a 3″ crust.)
Also consider fractional and negative inputs, if they make sense.
If your function has a String input, then include the empty string as a test case.
If your code contains if statements, have a test case to test each possible branch of that statement.

ρ (rho): Repeated code. Rather than repeat code, put the common code into a method and call the method from several places.
You might need to provide a chunk of varying (“variant”) information, and your new method encapsulates that part of the task which is invariant. The idea is that if you want to modify how the program acts in the future, you should have to change things in only one place.

μ (mu) Missing requirement: There is a function or method requested on the homework which you didn't provide. (And/or, you spent a lot of time writing something which was never actually asked for.) Please read the handout carefully!

δ (delta): Documentation. EVERY function for EVERY homework in EVERY course requires:

a short purpose-statement for the function. (≤ 1 sentence is best; good to mention your parameters by name; might be cribbed from the homework-assignment).
Related: unhelpful comments
A mention of what each parameter means, if not already clear from the purpose-statement and its name. Include any units (e.g. kilometers or pixels or seconds), if appropriate.
Make sure the return-type and param-types are mentioned . In Java, that info is already required just to compile; otherwise it should be in comments.
test cases

λ (lambda): Long-winded, verbose code: No points taken off for this, but observe that…

you can condense a statement of the form

if (someCondition) {
  return true;
  }
else {
  return false;
  }

into the more concise

return someCondition;

Similarly, if (expr == true) … can be simplified to if (expr) …. You can use ! (“not”) to compare against false: (expr == false) is more concisely expressed as (!expr).
Similarly, if you use a variable to remember some result, but then only use that result once (and on the very next line), you can probably just omit using a variable at all. For example
SomeType someVar = someExpression; return someVar;
can be tightened up to read just
return someExpression;

If you prefer the longer versions, that's okay, though as you get more comfortable with using values you'll find the shorter versions more understandable.

κ (kappa): Confusing/Unclear/unhelpful comments or variable names or code.

An example of unhelpful commenting:

/** The lines of code below are taking in an ID and returning a boolean.
 * @param id an ID.
 * @return true or false
 */
static boolean isSoldByWeight( String id ) …

A more helpful description:

/** Returns whether or not a grocery-item ID is for an item which is sold by weight.
 * @param id An ID `number', like "produce4011" or "inv47AGM231".  Must be a valid ID.
 * @return true if and only if the ID'd item is sold by weight.
 */
static boolean isSoldByWeight( String id ) …

Note that the one-line-summary is often nearly identical to the @return line.
For ibarland's classes, you may omit the @return line, in that case. (I wish Javadoc would do something like this by default, to maintain a single point-of-control -- a standard software goal!)
Also, if a parameter's name or function's name is clearly self-documenting, you can omit a description (as with id, in this case). (At the function-level, it had better be pretty dang self-documenting -- e.g. getters and setters, if the underlying field is itself self-documenting, or is already documented elsewhere.)

Here is one example of code which is misleading/confusing:

int i = n;   // misleading: 0 might be entirely wrong, and "patched" in the next line
if (n < 0) {
    i = 0;
    }

It's arguably poor practice to assign a wrong-value to a variable, and then go back and patch it up in the next line. Why not just initialize it with the correct value to start with?

int i;
if (n < 0) {
    i = 0;
    }
else {
    i = n;
    }

Admittedly, this has the additional characters "else { }", but it's now clear that the purpose of the entire if-else is to (correctly) initialize the variable declared on the preceding line. Often, situations like this can be shortened by using the (ternary) conditional operator ¹:

int i = (n < 0   ?  0  :  n);

or (in this case) even

int i = Math.max(n,0);

¹Some people dislike the conditional-operator for readability reasons: I agree, it's far too easy to lose the characters “?” and “:” in the rest of the statement. To ameliorate that, I suggest putting two spaces around those characters, and perhaps putting the entire expression in parentheses (or sometimes just the initial condition in parentheses). I prefer languages where the conditional has the same syntax as a function, e.g. Excel's “=IF(n<0, 0, n)” or Racket’s “(if (< n 0) 0 n)”. Regardless, being in the habit of returning an answer for both branches of the if helps reduce bugs. ↩

This page licensed CC-BY 4.0 Ian Barland
Page last generated 2018.Jan.21 (Sun)

Please mail any suggestions
(incl. typos, broken links)
to ibarlandradford.edu