Commenting Guide

Also see the Code Quality Guide

Introduction¶

In Java, comments are ignored by the compiler meaning that comments are not intended for the behavior of a program. Instead, comments are intended to be a helpful explanation of what your code does and how to use it. Writing good comments is intended to help clients and developers of your code (including yourself).

There is no single way to write a helpful comment. It may help to think from the client’s perspective. The client can read through your implementation to get an idea of what the code does, but the comment is meant to save the hassle and offer context. As such, a helpful question to ask when writing comments is, “if a client could not see my code implementation and just had this comment, would they be able to use the hidden piece of code?”. Asking this question reveals that we should comment on the behavior of the method, the inputs to the method, and the outputs of the method.

Comment Formatting¶

There are three main commenting 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¶

In CSE 121, you should include a header comment at the top of every program. This comment should include your name, the date, the class (CSE 121), your TA’s name, and the name of the program/assignemnt.

// Student Studentname
// 10.20.2022
// CSE 121 Section XX
// TA: Wrett Bortzman
//
// Programming Assignment N

Class Comments¶

Class comments are comments that describe a class or program as a whole. (All programs in Java are also classes– you’ll learn more about classes in CSE 122.) The purpose of a class comment is to give a client an understanding of what a class/program accomplishes at a high level. As such, class comments should be present in all classes and should describe all relevant functionality of a class/program. Thinking of your program as a really detailed book, the class comment would be a summary that describes things without too much detail.

Class comments should describe what your program does, but not how it does it (e.g. specific code constructs, libraries, constants, or program structure). These specifics are referred to as implementation details and are generally not important to clients of your code. In addition, including too much detail in the class comment will make it harder to keep the comments accurate when changes are made to the program later.

Example:

// This class is a budgeter. It takes in monthly or daily expenses and income. 
// It then draws conclusions about your spending habits.

Method Comments¶

Method comments are comments that describe what a method accomplishes, the inputs to the method (parameters), and the output of the method (return values). You can think of method comments as mini-specs of a method! All method comments should include a description of the method’s behavior, the parameters of the method (if any), and the outcomes of the method (Does it return a value? Does it manipulate a shared object/array?). Continuing the book analogy, you can think of a method comment as a chapter summary.

As with class comments, you should avoid implementation details when in your methods comments. 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. Such details about the implementation of the method only serve as clutter to the reader and can be easily missed if the implementation is changed later.

Method Comment Examples¶

Good Examples

// This method calculates net profit or loss based on monthly  income and daily spending
// Parameters:
//   - income: the user’s income this month
//   - spending: the amount the user spent each day this month
// 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);
}

// 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)
public static int calculateNetExpenses(int income, int spending){
    return income - (spending * DAYS_IN_MONTH);
}

Although this comment mentions that it calculates net profit or loss, it does not describe 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. To get this level of granularity, clients of your code could simply look at the implementation!

// 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){
    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 user-given.

// 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 comments written alongside chunks of code, usually within a method, to help explain complex or confusing code. Thse can be written on the line preceding the corresponding code, or if the comment and line are both short, at the end of the line. Inline comments are great for explaining tricky lines of code. You can include implementation details in inline comments since they are there to explain how a piece of code works.

public static void printRandomNums(int nums, int limit) {
    Random r = new Random();
    int max = 0;
    for (int i = 0; i < nums; i++) {
        // generates a random number from 1 - limit
        int num = r.nextInt(limit) + 1;

        if (max < num) {
            max = num; // keeps track of max generated number
        }
        System.out.print(num + " ");
    }
}