homework-3-tips.md

Hey everybody --

I just wanted to send out a few notes about homework. I saw some common issues while grading, and wanted to give some reminders, tips, and tricks which I think are going to be pretty useful for your upcoming homework assignment.

Commenting

When commenting method headers, make sure you always do the following:

1. Describe what the method does (without describing what the code does)
2. Describe what every parameter does
3. If the method returns anything, describe what is being returned.

We've talked about the first part in class, but I don't think I've ever talked about how to properly describe how to describe what your parameters do. Here's an example of how to correctly do it:

// This method multiples the two numbers 'a' and 'b', and returns
// the output. 
public static int multiply(int a, int b) {
    return a * b;
}

This would get full points since it mentions all the parameters by name, what they do, and what's being returned.

Here's another acceptable example:

// This method multiples two numbers.
// a: The first number to multiply
// b: The second number to multiply
// return value: The product of `a` times `b`
public static int multiply(int a, int b) {
    return a * b;
}

The second example is more verbose and repetitive then the first example (mostly because 'multiply' is sort of a silly method to write), but would also be ok.

Make sure to focus on what the code does, not how it works! Whatever comment we write should always be relevant, no matter how our multiply method is written. For example, if I rewrote our 'multiply' method to be even sillier, my comment would still accurately describe what the method does.

// This method multiples the two numbers 'a' and 'b', and returns
// the output. 
public static int multiply(int a, int b) {
    int sum = 0;
    for (int i = 0; i < a; i++) {
        sum += b;
    }
    return sum;
}

Long lines

When writing code, you should take care to avoid having lines of code that are too long. If a line of code is over 100 characters wide (including the indentation at the start), then it's too long. I thought I'd go over some strategies for dealing with long lines.

Here's an example method:

public static void drawNestedSquares(Graphics brush, int x, int y, int size, int numNested) {
    for (int i = 0; i < size / numNested; i++) {
        brush.drawRect(x + i * (size / numNested / 2), y + i * (size / numNested / 2), size - i * (size / numNested), size - i * (size / numNested));
    }
}

One method for shortening lines is to observe what segments of code are being repeated, and pull them out into their own variable:

public static void drawNestedSquares(Graphics brush, int x, int y, int size, int numNested) {
    for (int i = 0; i < size / numNested; i++) {
        int gap = i * size / numNested
        brush.drawRect(x + gap / 2, y + gap / 2, size - gap, size - gap);
    }
}

This brings the longest line down to a much more readable 78 characters.

Another method you can use is to move each parameter to its own line:

public static void drawNestedSquares(Graphics brush, int x, int y, int size, int numNested) {
    for (int i = 0; i < size / numNested; i++) {
        brush.drawRect(
            x + i * (size / numNested / 2), 
            y + i * (size / numNested / 2), 
            size - i * (size / numNested), 
            size - i * (size / numNested));
    }
}

If you look at the 'brush.drawRect' method, I've taken each parameter, moved it to a new line, and indented. If you chose to use this method, make sure to always indent, and always indent by the same amount!

How much you chose to indent doesn't particularly matter as much, as long as you're consistent. For example, this is also ok:

public static void drawNestedSquares(Graphics brush, int x, int y, int size, int numNested) {
    for (int i = 0; i < size / numNested; i++) {
        brush.drawRect(
                x + i * (size / numNested / 2), 
                y + i * (size / numNested / 2), 
                size - i * (size / numNested), 
                size - i * (size / numNested));
    }
}

This technique does add to your line-count, which I know some of you worry about. However, readability is far more important then minimizing the number of lines of code you have.

---

You can also do the same thing when declaring methods -- we could have easily changed our method header to be:

public static void drawNestedSquares(Graphics brush, int x, int y, 
                                     int size, int numNested) {

However, while this is perfectly valid, having too many parameters in a method is often an indication that the method is doing too much, and should be broken up into smaller methods.

For homework 3, there really wasn't much you could do -- each method did need a larger amount of parameters then usual. However, in the future, definitely keep an eye out on your parameters.