Commenting Guide

Motivation¶

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 of your code.

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¶

At the top of all programs, for this class, you should include a header comment with your name, date, class, your TA’s name, and the name of the program.

Example:

// Your Name
// MM/DD/YYYY
// CSE 121 Section XX
// TA: TA Name
//
// Programming Assignment N

Class Comments¶

Class comments are comments that describe a class as a whole. The purpose of a class comment is to give a client an understanding of what a class accomplishes at a high level. As such, class comments should be present in all classes and should come directly after your header comment. Class comments should describe all relevant functionality of a class.

Thinking of your program as a really detailed book, the class comment would be a summary that describes things without too much detail.

Example:

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

Note

Header and class comments should be placed before all code, including any import statements

Method Comments¶

Method comments are comments that describe what a method accomplishes, the inputs to the method, and the output of the method. 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, and the outcomes of the method (Does it return a value? Does it manipulate a shared object?).

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

Behavior - What the method does.
Exceptions - Documenting any errors the method might raise on invalid input
Returns - What the returned value is
Parameters - What the parameters are

All things that should be mentioned in a method comment if applicable. Continuing the book analogy, you can think of a method comment as a chapter summary. Something to keep in mind is that we also want to avoid implementation details when writing our 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.

Complete Comment 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);
}

Incomplete Comment Examples¶

Missing Parameter Comments

// 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);
}

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

Implementation Details

// 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);
}

This comment contains unnecessary implementation details. To get this level of granularity, clients of your code could simply look at the implementation!

Missing Return Comment and Unclear Parameter Comment

// 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);
}

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.

Inline Comments¶

Inline comments are comments written in chunks of code. They can be in between lines of code, or at the end of them and serve to explain tricky lines or sections of code. Inline comments are great for explaining tricky lines of code. You don’t need to worry about implementation details in inline comments since they are there to explain how a piece of code works.

public static int calculateNetExpenses(int income, int spending) {
    return income - spending; // This is an inline comment!!!
}