Home Commenting methods

Like any form of writing, it's very important to know who exactly your audience is before starting. That way, you know what sort of tone you should be taking, what kind of information is relevant, and what sorts of things to focus on.

Because we want you to get practice in how to write high-quality comments (the kind that other professional programmers would expect), we want you to assume that whoever will be reading your comments fits the following profile:

• Assume your readers are competent programmers.

  That means you should not spend the time explaining how things like a for loop or a println works. Assume that your reader is already familiar with Java to a reasonable extent.

• Assume your readers know nothing about the assignment.

  You should assume that your reader knows nothing about your program, what it is, what it's supposed to do, and why it exists (perhaps they didn't take classes at UW). They just need to understand how to interact with your code.

• Assume your readers don't care about how exactly your code works, only how to use it.

  We will revisit and elaborate on this assumption in CSE 143, but for now, you should assume that whoever is reading your method header comments is doing so because they need to interact with your code in some way. That means you should spend a lot of time elaborating on what your parameters are (and what values are acceptable), and what effect calling that method has/what values you'll return.

  However, they don't care how precisely that method works, whether you're using a print or println or anything to that effect.

  IMPORTANT: This bullet point only applies to method header comments, NOT to inline comments (comments inside a method). If somebody is reading your inline comments, that means that they are interested in how exactly your method works. In that case, this assumption wouldn't apply.

This neatly summarizes the profile of a typical professional developer. (It's very common for professionals to collaborate + reuse other people's code. It's also very common for professionals to be on a deadline and not have time to actually dive deep into whatever they're using).

Here are some common mistakes that students will make when they forget to keep their target audience in mind:

• Assume the readers has read the spec/can read the spec.

  So, you should not say things like "for a full description, see page X-Y in the spec".

• Address their comments to the TA.

  Remember, the TA is not your intended audience, and you should not be catering your comments to them. If you really do feel the need to address your TA directly, leave it as an inline comment (and explicitly indicate that this is not a normal comment).

We expect you to comment every single method written in your class, even if they seem very simple.

Your comments must describe what the method does, but not how it does it. You should assume that whoever is reading your comments is very interested in learning how to use your method, but does not care how it works or what it internally looks like. Again, this simulates what the typical programmer will be looking for in comments in industry.

That said, your comments also should not be too short.

For example, take the following method:

public static void printMultiplicationTable() {
    for (int i = 1; i <= 10; i++) {
        for (int j = 1; j <= 10; j++) {
            System.out.print(i * j + "\t");
        }
        System.out.println();
    }
}

This would be a bad example of a method header comment.

// Prints a multiplication table
public static void printMultiplicationTable() {
    ...
}

This comment is too brief. It hardly answers the most basic question of "what does the method do?"

// Uses two nested for loops and print statements to print a multiplication
// table. Both loops start at 1 and go to 10. System.out.println() is used
// every ten numbers to move the table to the next line.
public static void printMultiplicationTable() {
    ...
}

This version of the comment is too elaborate. It mentions that the method prints a multiplication table that goes to 10, but it also includes unnecessary details about the method's implementation. Knowing that the method uses nested for loops doesn't change how a client will use the method.

// Prints a tab-separated 10 by 10 multiplication table.
public static void printMultiplicationTable() {
    ...
}

This comment is much better. It concisely yet thoroughly describes the method's behavior.

The reason why commenting your main method is optional is because there is an extremely high chance that your comment is going to be near-identical to your class header comment, since both comments essentially describe the entire program.

However, if you do try and do so, feel free to do so. It's sort of pointless, but will not detract from your program.

Besides describing what your method does, you should also spend some time describing any parameters your method accepts, and what values it returns (if any).

Provide enough information that somebody calling your method understands what values they're allowed to plug in, and what they can expect as output.

For example, this is an example of a method which does not adequately comment on parameters and output:

// Moves a robot
public boolean moveRobot(double distance, double angle) {
    // ...
}

While it does describe what the method does, it doesn't fully describe what its parameters are, or what it returns. Here is a better example:

// Moves a robot forward by the given distance at the specified angle.
// Returns 'true' if the robot was able to move the specified distance
// without running into any kind of obstacle.
//
// The specified distance must be in meters, and cannot be negative.
// 
// The angle must be in degrees, and in the range -90 to 90 (inclusive).
// If the angle is positive, the robot curves right. If the angle is negative,
// the robot curves left. If the angle is positive, the robot curves right.
// If the angle is equal to 0, the robot moves forward.
public boolean moveRobot(double distance, double angle) {
    // ...
}

This is a much better method header comment – it explicitly mentions each parameter, their expected ranges, their units, and all other information somebody might need to use it. It also mentions what the method returns, and any other relevant information.

We do not require your comments to be formatted following any particular convention. Here are some suggested commenting formats:

// Your name here
// TA name
// January 8, 2033
// Assignment 1
// 
// This commenting style uses a series of single-line comments
// for everything.
public class Example {
    public static void main(String[] args) {
        // ...
    }

    // Notice that there is one blank line between one method
    // and the next, but no blank line between the comment and
    // the thing that it is commenting.
    public static int foo(int a, int b) {
        // ...
    }

    // You also don't have to write everything in a single paragraph.
    // Feel free to add
    // 
    // line breaks and
    //
    // - bulleted
    // - lists
    public static int bar(int c, int d) {
        // ...
    }
}

You can also use multi-line comments:

/* Your name here
 * TA name
 * January 8, 2033
 * Assignment 1
 *
 * Here, I'm using multi-line comments. Even though I don't need to,
 * I'm prefixing the start of each line with a star because it
 * looks prettier.
 */
public class Example {
    public static void main(String[] args) {
        // ...
    }

    /* Same thing here -- multi-line comments.
     */
    public static int foo(int a, int b) {
        // ...
    }

    /* And again, another comment. All of the guidelines from
     * up above still apply.
     */
    public static int bar(int c, int d) {
        // ...
    }
}

If you know what Javadocs commenting style is, feel free to use that also:

/**
 * Your name here
 * TA name
 * January 8, 2033
 * Assignment 1
 *
 * Do note that you still need to include the metadata up above, even
 * though it's not a part of the Javadocs standard.
 *
 * <p>If you want to use a subset of Javadocs or come up with your own
 * standard, feel free to, as long as it's readable and consistent.
 */
public class Example {
    public static void main(String[] args) {
        // ...
    }

    /**
     * All of the same guidelines apply.
     *
     * @param a  does something
     * @param b  does something else
     * @return   blah 
     */
    public static int foo(int a, int b) {
        // ...
    }

    /**
     * Just don't switch between styles in a single assignment.
     * It looks messy.
     *
     * @param c  description 
     * @param d  more description 
     * @return   even more description 
     */
    public static int bar(int c, int d) {
        // ...
    }
}