ITEC 120 2007fall ibarland, jdymacek

home—info—exams—lectures—labs—hws
Recipe—Laws—lies—syntax—java.lang docs—java.util docs

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: if one line is a sub-part of another, then indent it. For instance:
  • The body of a loop is indented relative to the first line of the loop.
  • The lines inside a method are a sub-part of that method.
  • Methods in a class are indented inside the all-encompassing class declaration at the top of the file.
  (Consider how reading this very paragraph is easier, because of how the web browser indents items of a lists.) Also,
  • include blank lines between different methods (since they are separate parts, like separate paragraphs).
  • Don't put blank lines between comments and the code being commented about.
  • Include spaces between words and punctuation, as needed.
  For examples of good, readable code, look at any code in the class notes or in the book.
• δ (delta): Lack of documentation / javadoc.
  Include one @param for each parameter (explaining what it means), and one @return if the method is non-void.
  You should be able to look at the interface-view, and put yourself in the mindset of a fellow programmer who wants to call your functions. Do you provide enough information?
  Note that your javadoc does not discuss how your program works (its implementation), but rather what your program does (its interface).
• κ (kappa): Unclear/unhelpful/misleading comments or variable names.
  Function-names should reflect what they do or return, and variables names should reflect what value the variable holds.

  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 An ID `number', like "1572935" or "47AGM231". Must be a valid ID. * @return true if and only if the ID'd item is sold by weight. */ static boolean isSoldByWeight( String id )

  True, it is annoying to repeat the same info twice¹; often (but not always) the @return line is also a succinct overall description.

• Κ (Kappa): A name should start with upper-case only² if it's the name of a class The only exception is named-constants, which should be in all-caps. (and nothing else should).
• τ (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.
• ν (nu): No Magic Numbers. Use a named constant (all-caps, declared outside of any method.)
• η (eta): Use .equals(·) to compare Strings, not ==. In general, be sure to understand the difference == between these two notions of equality; come to office hours if unsure.
• λ (lambda): Long, roundabout code. A few points taken off, except for the following three situations:
  • 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.
• μ (mu) Missing/wrong requirement: There is a method requested on the homework which you didn't provide, or you are doing something different than what was actually asked for. Please read the handout carefully!
• γ (gamma) Use getter/setter, rather than access the field directly.
• θ (theta) I recommend writing out “this.” yourself, rather than rely on Java writing it in for you.³
• φ (phi) Every if needs an else. Although Java allows if without an else, when you are using an if-else for initializing a variable, or for returning an answer, then each branch of the if should do this.
  (Note that once we discuss setter methods, one-armed-ifs can be used in that situation.) (No points taken off for this.)
• π (pi): no public or private.
  (Applies only after these keywords have been included in lecture, of course.)

home—info—exams—lectures—labs—hws
Recipe—Laws—lies—syntax—java.lang docs—java.util docs

©2007, Ian Barland, Radford University Last modified 2007.Nov.28 (Wed)

Please mail any suggestions (incl. typos, broken links) to iba�rlandrad�ford.edu