Motivation¶

In Java, comments are ignored by the compiler; in other words, they don’t affect the behavior of a program. Instead, comments are intended to be read by humans. They should explain to others what your code does and how to use it. Writing good comments is a social activity (and a communication skill).

Learning how to write good comments is a challenging skill, and there is no “best” comment. However, it helps to put yourself in someone else’s shoes. What would a coworker (who knows just about as much programming as you) need to know as they read through your code? In particular, your comments should not just repeat your code; it should either summarize what your code does at a higher level, or provide an insight that might not be obvious by just reading your code.

In 121, we will focus (and assess you) on:

• commenting each program you write (with a class comment)
• commenting each method that you write (with a method comment)

In these contexts, a question we’ll frequently ask is, “if someone else could not see my code and just had this comment, would they be able to use my code effectively?”

Note: in future CSE classes, e.g. CSE 122 and 123, we’ll expand the breadth and depth of comments we write as our programs become more complicated.

Comment Formatting¶

Java programmers tend to use one of three comment formatting styles:

// Comment
// Style
// #1


/* Comment
   Style
   #2 */

/**
 * Comment
 * Style
 * #3
 */

In this course, we welcome you to use your personal commenting style! Make sure to keep your commenting style reasonable and consistent throughout your code.

Header Comments¶

At the top of all programs that you write in this class, you should have a header comment. This should include your name, the date you wrote the program, the class, the assignment, and your TA’s name. You can think of this as “signing” your assignment.

For example:

// Matt Wang
// 02/31/1989
// CSE 121
// P0: Warm Up
// TA: Miya Natsuhara

Class Comments¶

A “class comment” describes a Java class as a whole. For the purposes of CSE 121, we want your class comment to describe your program as a whole. This comment should not just repeat what each line of code in your class does; instead, it should describe all relevant functionality at a high level.

One common analogy involves thinking of your program as a detailed book. Within this analogy, a class comment is a summary (like one you’d find in a book review or on Wikipedia) — that describes things without going into too much detail.

For example:

// Kasey Champion
// 02/31/1989
// CSE 121
// TA: Brett Wortzman
// C2: Building Brett Better Budgets
// This class is a budgeter. It takes in monthly or daily expenses and income. It then draws
// conclusions about your spending habits, and prints some suggested tips.
public class Budgeter {
    // CODE HERE
}

A class comment should come immediately after your header comment, and before any import statements.

For example:

// Kasey Champion
// 02/31/1989
// CSE 121
// TA: Brett Wortzman
// C2: Building Brett Better Budgets
// This class is a budgeter. It takes in monthly or daily expenses and income. It then draws
// conclusions about your spending habits, and prints some suggested tips.

import java.util.*;

public class Budgeter {
    // CODE HERE
}

Method Comments¶

A “method comment” describes a method in terms of its observable behavior, its inputs, and its outputs. It can be helpful to think of method comments as “mini-specifications” of a method! Continuing the book analogy, you can think of a method comment as a chapter summary.

In CSE 121, we ask that all method comments include a description of the method’s behavior, the parameters of the method, and the “outcomes” of the method (does it return a value? print output? manipulate a shared object?).

We suggest using one of two commenting conventions: “BRP” (pronounced “burp”) or Pre/Post. It is your preference on which one to use on assignments, and you do not need to use both. Each convention has its advantages and disadvantages, but both convey all the necessary method information listed above.

BRP Commenting¶

One helpful acronym you might hear TAs mention is BRP! It stands for:

• Behavior - What the method does
• Returns - What the returned value(s) are
• Parameters - What the parameter(s) are

Pre/Post Condition Commenting¶

A different way to think about methods is with pre and post-conditions:

• a pre-condition for a method defines its accepted range of inputs. Only input that meets these criteria are guaranteed to produce correct output. All other input (that does not meet the pre-condition) may compute an incorrect output.
• a post-condition for a method defines its behavior and range of outputs. If the input meets the pre-condition, the output must be in the range of output.

An imperfect translation between BRP and pre/post commenting:

• pre-condition comments usually explain what valid Parameters a method would take
• post-condition comments usually explain the overall Behavior of the method and its Return values

Implementation Details¶

While it might be tempting to document each line of code in your program, this is not always helpful. For example, we don’t need to document that our method accomplishes what it does by using a loop — someone reading our code can figure that out just by looking at the method! Mentioning too many details can be tedious for a reader (and makes it harder to emphasize what’s important).

In CSE 121, we suggest that your class and method comments don’t contain “implementation details”: low-level explanations of your code that someone using it wouldn’t need. Learning what an implementation detail is (opposed to “important” documentation) is challenging and takes time, but a non-exhaustive list includes:

• syntax constructs you use (e.g. “this method uses a for loop” or “this method uses an if statement”)
• temporary variables or objects that you create
• step-by-step calculations

Comment Examples¶

Complete Comment Examples¶

BRP¶

// Behavior:
//   - This method calculates net profit or loss based on monthly income and daily spending.
// Parameters:
//   - income: the user's income this month (should be non-negative)
//   - spending: the amount the user spent each day this month (should be non-negative)
// Returns:
//   - int: the net profit or loss. Positive if profit, negative if loss.
public static int calculateNetExpenses(int income, int spending) {
    return income - (spending * DAYS_IN_MONTH);
}

Pre/Post¶

// Pre: accepts a non-negative int income representing the user's income
//      and a non-negative int for user's daily spending.
// Post: calculates net profit or loss based on monthly income and daily spending.
//       and returns the net profit (positive) or loss (negative)
public static int calculateNetExpenses(int income, int spending) {
    return income - (spending * DAYS_IN_MONTH);
}

General¶

(paragraph format; neither Pre/Post or BRP, but communicates all necessary info)

// This method calculates net profit or loss based on a given monthly
// income (int) and daily spending (int). It then returns the net
// profit or loss of the user (int). Both inputs should be
// non-negative (i.e. greater than zero)
public static int calculateNetExpenses(int income, int spending) {
    return income - (spending * DAYS_IN_MONTH);
}

Incomplete Comment Examples¶

Missing Parameter Comments¶

Although this comment mentions that it calculates net profit or loss, it does not touch on the parameters of this method.

// This method calculates net profit or loss, and returns it to the
// user.
public static int calculateNetExpenses(int income, int spending) {
    return income - (spending * DAYS_IN_MONTH);
}

Implementation Details¶

This comment contains unnecessary implementation details. For this level of specificity, someone could just look at your code!

// This method takes income and spending and uses the formula income -
// (spending * days in a month) to return the user's net income.
public static int calculateNetExpenses(int income, int spending) {
    if (income < 0) {
        throw new IllegalArgumentException("Income can't be a negative integer!");
    }
    return income - (spending * DAYS_IN_MONTH);
}

Missing Return Comment and Unclear Parameter Comment¶

This method comment is missing a return comment. Additionally, it is unclear whether income and spending are parameters as there is no indication in this comment they are provided by the user.

// This method calculates net profit or loss based on monthly income and daily spending.
public static int calculateNetExpenses(int income, int spending) {
    return income - (spending * DAYS_IN_MONTH);
}

Inline Comments¶

Inline comments are written within (or in-line) a method or class. They can either be between lines of code, or at the end of a specific line.

They serve a different purpose than method and class comments: their primary goal is to explain tricky lines or sections of code. Because they have a different goal than method and class comments (and are read by someone already looking at your code), they often will discuss implementation details (and this is totally fine - that’s their goal)!

public static int calculateNetExpenses(double income, double spending) {
    // This (int) rounds the netExpenses to the nearest integer, to match the requested format
    return (int) income - spending;
}

In CSE 121, we encourage you to write these comments for yourself when they are helpful, but will not assess you on them.