-----------------------------------------
 Graders' perspective on commenting AS 1
-----------------------------------------

I just finished grading my portion of assignment 1, so some of you should
be getting them back graded as soon as I can get the mailback script to
work. Here are a few notes on things that I noticed a lot of people had
trouble with. 

Most people did a pretty good job of getting their code to work, but there
were several trouble spots. If you had any trouble with any of the
problems, definitely take a look at the homework solutions, which I think
are either already posted in the assignment directory, or will be soon.

A lot of people had trouble with power(), superpower(), and
superlog(). Most commonly, it was a problem of properly defining the base
case. It is very important to read the problem specification closely to
see exactly what inputs you can expect, and what output you should
provide. For example, power(X,Y) can take as input any Y greater than or
equal to 0. Many people defined the base case power(X,1) => X, which is
correct, but leaves you with no way of dealing with power(X,0), which is a
valid input. 

The key to avoiding those sorts of mistakes is to read the problem
specification carefully, and to be sure to test your code at the 
boundary values. Most bugs in these sorts of problems come at the
boundaries- extreme values where special conditions may apply. In this
case, Y=0 is a boundary value because it is the lowest Y can go. In order
to accomodate this case, the proper base case should be power(X,0) => 1.

Most of the problems I saw, however, were problems of style (where style
is a general term including commenting, formatting, and everything else
besides the actual functionality of the code). This is normal for the
first assignment, which is why your style scores were not counted this
week. They will be, starting next week, and almost everyone has some style
issues they need to work on.

First and foremost is commenting. Nearly everyone included some comments
explaining what each required function did. This is correct, and
important, but isn't enough. You also need to explain how the function
does what it does. For simple functions, like the first 5 or so problems,
this is unnecessary (any reader with a knowledge of rex can probably
figure out how add42() works), but as the problems get more complex, you
need to give more detailed explanations. 

One easy way to do this is with helper functions. It is often very useful
to organize complex problems by writing helper functions which solve
smaller sub-problems. If you do so, you must comment those functions,
just as you would for the functions required by the assignment. These
comments don't need to be long, but need to explain the beahvior of the
helper function. Then, for the larger functions, you just need to explain
how they use the helpers to arrive at the final result.

In general, it is a lot easier to comment as you go, explaining your code
while it is fresh in your mind. Moreover, putting off all the commenting
until the end just makes it an unbearable chore, especially as the
assignments get longer.

A lot of people also had trouble with formatting. As function definitions
get longer, they get harder and harder to read. In order to make long
function definitions more comprehensible, it is important to break them up
into several lines. This is perfectly safe from a programming standpoint-
the rex interpreter treats line breaks the same as spaces. You also need
to indent multi-line functions in order to clarify their structure. How
you do so is largely a matter of personal taste, but it does need to be
clear to the reader. Here's an example:

Bad:

bestThree(r,L) = empty(L)? [0, ""] : betterWord([scrabbleScore(first(L),letterScores),first(L)],bestThree(r,rest(L)),r);

Better:

bestThree(r,[])    => [0, ""];
bestThree(r,[F|R]) => betterWord( [scrabbleScore(F, letterScores), F], 
                                  bestThree(r, R), r );

Notice how I used whitespace and indentation to clarify this
function. Notice also how I changed it to use rewrite rules and pattern
matching to make it a lot clearer and cleaner than using a single
definition and ?: statements.

On a related note, make sure that none of your lines is more than 80
characters wide, the width of a standard terminal window. The easiest way
to make sure you follow this rule is not to resize your editor window-
emacs starts up as a window 80 characters wide. If you leave it that way,
it's easy to tell when you're going over the limit- if emacs ends a line
with a '\' character and wraps to the next line, your line is too long.

A final reminder- the tutors and graders are here to help you! Come down
to the terminal room during tutoring hours, of which there are many, and
we can help you out. I can't speak for the others, but I'm in the lab 2-5
on Fridays, and the place is nearly empty. If you can't make it to the
lab, the cs60help mailing list is another option, and hardly anyone's been
using it. If you need help, there are all kinds of places to get it-
please take advantage of them!

  Geoff Romer