The style grinch is back, bearing notes on assignment 5 (Yes, I'm a little
behind).

First of all, I was a little surprised to still be seeing overlong
lines. Please, make sure your lines are under 80 characters wide! It's
very easy to do, and it will save you 2 points. There's no reason to
still be making this mistake.

Next, a note or two on commenting (surprise!). I'm seeing a lot of people
who will write one enormous (or worse, not so enormous) comment at the top
of a method like Maze.solve(), and then leave the entire body of the
method uncommented. This is not a very good practice. Good commenting
requires a balance between header comments, which give an overview and a
plan of attack, and in-line comments (I sometimes called them
"play-by-play" comments in my grading) within the function itself,
explaining the nitty-gritty. Here's a quick example of what I'm talking
about, a function to find the minimum of an array. (If there are any
syntax errors, I apologize, but the point here is the commenting)

/*
 * min takes an array of ints a and returns the smallest value in the
 * array
 */
int min(int[] a)
{
    int currentMin;             //Stores the minimum of the items searched
    currentMin = a[0];          //Initialize currentMin
    for(int i = 0; i < a.length; i++)
    {                           //Loop over array a
	if(a[i] < currentMin)   //If we have found a new smallest value
        {
            currentMin = a[i];  //Make it the new current minimum
        }
    }
    return currentMin;          //After loop, currentMin must be overall min
}

The specifics of the commenting style are a matter of personal preference,
but the sort of in-line comments you see in the right half of the code are
very useful for clarifying your code. Notice that I do not need to explain
the startegy in the header because it is very simple, and the in-line
comments make it clear. (In practice, a function this simple wouldn't need
all that commenting.)

I saw several people who misused (or didn't use) the public and private
keywords. As a rule, with very rare exceptions, all members of a class,
whether functions or data, should be explicitly declared public or
private. All data members should be declared private, except in very rare
cases that won't come up in any of the assignments you do this
semester. The reason for this is abstraction- users of your class
shouldn't need to know about the class' innards, much less have to
interact directly with them. All interaction with a class should go
through its interface- the public methods it defines.

Consider the following snippet, which I saw in various forms in several
assignments:

class MazeCell
{

    private bool marked;

    /*
     * sets marked to value
     */
    public void setMarked(bool value)
    {
        marked = value;
    }

    /*
     * gets the value of marked
     */
    public bool getMarked()
    {
        return marked;
    }
}

This is a very common approach to private members- if the data member must
be private, write get and set methods to alter it. This is an improvement,
but the names and comments are poorly chosen, because they refer to what
the functions *do*, rather than what the functions *mean*, and they define
public methods in terms of private data. Sure, what setMarked() *does* is
set the value of the 'marked' variable, but what does that mean? This
comment is totally unhelpful to the user of the code, who should not have
to know anything about the internal variables in order to use the
class. The *meaning* of setMarked() is that the cell is being marked as
already searched, and the *meaning* of getMarked() is to check whether the
cell has been searched. Thus, a much better choice of names and comments
would be

class MazeCell
{

    private bool marked;

    /*
     * Marks the cell as having been searched
     */
    public void mark()
    {
        marked = true;
    }

    /*
     * returns whether the cell has been marked
     */
    public bool isMarked()
    {
        return marked;
    }
}

This redefines essentially the same structure in terms of the abstractions
which the MazeCell class represents (marking the cell) rather than
implementation specifics (setting the value of a variable which happens
to be named 'marked'). Notice also that I've removed the argument to
mark(). This is because setMarked(false) has no real meaning- there's
no reason to "unmark" a cell.