- μ (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!
- ι (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 its 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.
- δ (delta):
Poor or missing documentation or javadoc.
Each method should include a short description of what it returns;
be sure to mention each parameter by name (else you are expecting the reader
to be psychic).
More precisely:
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 it's not already clear from the purpose-statement and its name.
-
Make sure the return-type and param-types are mentioned.
In Java/Ada, that info is already required just to compile;
for javascript/racket/python/etc it should be in comments.
Note that good function-names and parameter names go a long way
towards self-documentation.
If you have a name/field that uses an abbreviation, include a quick comment explaining:
int numPpl; // "number of people"
/* Return the index of `needle` inside `haystack`, or null if it does not occur. */
@Nullable
Integer locate( int needle, List<Integer> haystack )
|
Include any units (e.g. kilometers or pixels or seconds), if appropriate.
Put yourself in the mindset of another programmer who might want to call your
function: Do they have all the information they need?
Note that your documentation should not discuss
how your program works (its implementation),
but rather what your program does (its interface).
If comlete Javadoc is required:
Include one @param for each parameter (explaining what it means),
and one @return if the method is non-void.
Look at the resulting HTML documentation, and make sure it reads correctly.
(ibarland won't require full javadoc unless specified on the homework,
if the other guidelines above are followed.)
- κ (kappa):
Confusing/Unclear/unhelpful comments or variable names.
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 )
|
-
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,
unless otherwise specified on the particular assignment.
(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.)
- τ (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.
- λ (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
-
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.
- η (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.
Similarly, doubles/floating-point numbers should be compared
with a method that allows for some tolerance, rather than exact-equality
(== or Double#equals).
Separately:
If you override equals, you should
also override hashcode.
- γ (gamma) Grammar/spelling.
- φ (phi) Fluffy (mostly for term-papers):
You might be able to omit this comment or sentence entirely,
and still convey the same info.
When writing papers,
this indicates that your paper would still make exactly the same point with a much-shorter
(or entirely omitted) sentence.
Perhaps, it's a generic statement that is common knowledge, and it seems like
you're just saying it to fill up time.
E.g. “The internet is used by more and more people every year, and has come to play
an important part of commerce, socializing, e-mailing, and communication.”
Only include such a statement if it's really a key factor to the overall argument you're making,
and if you are later coming back to refer to several specific parts of that statement.
radford.edu