ITEC120-ibarland (incl. office hrs)—info—lectures—labs—hws—java.lang docs—java.util docs
hw05 grading guide:
preliminary
(As of Nov.12, I am partway through grading,
but wanted to mention common problems.
The most fundamental problem was κ.
Also, ζ and η need work.
Some common errors, marked with greek letters (lower-case).
(See also, common proofreading marks.)
- α (alpha):
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 with
(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.
- β (beta):
Lack of 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).
- γ (gamma):
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.
- δ (delta):
Missing function:
There is a method requested on the homework which you didn't provide.
- ε (epsilon):
Slightly 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
-
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
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.
- ζ (zeta):
Incomplete test method.
Your test method should test each method you write, with an appropriate number of test cases. E.g. one test case suffices for createLint(), at least two are needed for isLint() (once on lint, once on non-lint), and perhaps several are needed for drop() and grab(·)
since those two methods interact, so testing involves interleaving several
calls to each.
- η (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.
- θ (theta):
You could make this string message a bit nicer for the user
(by providing a bit of context about the message,
or making the message grammatical,
or using spaces or tabs or newlines,
or not using too much space/newlines,
or setting off the info inside of brackets).
κ (kappa):
If (say) a Treasure is added to a pocket, then have your code mirror the actual game: set the field leftPocket to be that Treasure. Do not just leave the existing item in the pocket (perhaps modifying its name, but leaving the same essential object there).
String grab(Treasure t) {
//...
leftPocket.setName( t.getName() );
//...BAD...
}
|
If there are multiple references to the original
Treasure in leftPocket, then the above code is dismal;
if the original item was also coolestTreasureEver, then the above code would suddenly think that coolestTreasureEver's name had changed (when it didn't; it just got dropped from somebody's pocket, but it didn't change).
Compare: That's like if the Registrar had a reference to the valedictorian (the Student named (say) Joe), and then as new grades came in and they decided some other student would be valedictorian: should they just go to Joe's personnel record, and change his name to Jane? Even if they set the phone# and dorm and etc to Jane's phone# and dorm, this is still egregiously wrong: Now, the parking office (who also had a reference to Joe, for an overdue ticket) will be calling up Jane's phone#, and asking for somebody named "Jane".
String grab(Treasure t) {
//...Good approach: ...
leftPocket = t;
//...
}
|
- λ (lambda):
Unclear/unhelpful comments.
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 the ID is for an item which is sold by weight.
* @param An ID `number', like "1572935" or "47AGM231".
* @return whether or not the ID is for an item which is sold by weight.
*/
static boolean isSoldByWeight( String id )
|
True, it is annoying to repeat the same info twice, but often (not always)
the @return line is also a succinct overall description.
(This is a lack of a single point of control, forcing me
to have the same information cut/pasted in two places.
Really, the program which generates a web page from your
program should use the @return line as the overall description,
if an overall description isn't otherwise provided.)
ITEC120-ibarland (incl. office hrs)—info—lectures—labs—hws—java.lang docs—java.util docs
radford.edu