-----------------------------------------
 Graders' perspective on commenting AS 2
-----------------------------------------

A couple of observations from grading assignment 2:

First of all, at risk of beating a dead horse, *comment*! As I said last
week, not only do you need to explain what your functions do, you need to
explain how they work. Again, be absolutely sure to comment your helper
functions- this will get you 90% of the way there. I'm not looking for
high word counts here, I'm just looking for a clear, simple explanation of
the outlines of the algorithm you used.

The other, related issue that's starting to come up more is variable and
function naming. Your graded assignments have a category "reasonable
variable names". This is a misnomer- the most important issue with naming
is the naming of your functions. For the main functions, this is done for
you by the assignment, but you need to chose good names for your helper
functions as well. This related to commenting- a good function name can
say more than a dozen lines of commenting, and consequently I will not
expect as much commenting if you make up the difference with good names.

The definition of a "good" name is a bit fuzzy, but my basic criterion is
"does the name reflect the meaning of the function?" The purpose of names
is to convey meaning to your human readers. What follows are some rules
of thumb that I find helpful in chosing names.

First of all, functions are verbs or questions. Their purpose within a
program is either to take some action, or to answer some question. Name
them accordingly. For example, suppose you are writing a function to test
if a number is odd. 

   Very bad: myFunction()
   bad:      test()
   ok:       checkParity()
   good:     isOdd()

These are arranged in order by how much information they convey to the
reader. myFunction() is just horrible. It tells me only that it is a
function, which I already know. test() isn't very good either. Yes, the
function is a test, but a test for what? checkParity() is ok, and may seem
cool at first glance because it uses impressive words like
"parity". However, this name leaves the return value ambiguous- what does
"true" mean- is the number odd or even? Also, the term "parity" applies
to other concepts besides odd and even, so the name is inspecific. 

isOdd() solves this problem. Just from the name, I know nearly everything
I need to know about the function- the argument (a number), the return
type (boolean), and the meaning of the return value (true means odd, false
means even). Also, it is the only one of the four function names which is
phrased as a question. Since the function in essence is a question, it
should be named as such. As a general rule, I name almost all of my
boolean-valued functions as questions (usually beginning with "is").

For more complex functions, the situation is not so clear-cut, but
from these ideas you should be able to come up with a good name
without too much trouble. I'm not going to be too strict in grading this-
anything better than the first two would get full credit from me.

As a sidebar, single-letter variable names are the convention in Rex, but
now that we're getting into Java, you're better off using full-length
variable names. The idea for naming variables is the same as naming
functions- variables are usually the nouns of computer languages, so try
to name them as nouns, in a way that clarifies their purpose and meaning
within the program.

  Geoff Romer