Motivation¶
Comments are ignored by the compiler, meaning they are not intended to affect the behavior of a program. Nevertheless, it is important to recognize that writing comments is an essential part of producing good quality code.
When we are learning a new language feature, we rely on documentation to tell us what that feature does and how to use it. For example, take a look at this real-world documentation for a Java String .substring method – notice how we didn’t have to see the underlying code, and yet we have all the necessary details to understand and use the method!
In the same way, writing good comments is intended to offer a helpful explanation of your code to clients. 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?”
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 Comment¶
At the top of all programs, you should have a header comment with your name, TA name, class, date, and name of the program. The purpose of the header comment is to provide basic information about the file.
Class Comment¶
Directly underneath the header comment, you should have a class comment that describes the 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, these comments should be present in all classes and should describe all relevant functionality of a class. When applicable, the class comment should also mention what interface(s) the class implements. Thinking of your program as a really detailed book, the class comment would be a summary that describes things without too much detail.
Here is an example of a header comment and class comment that might appear together at the top of a budgeter program:
// Boa Nerman
// TA: Niya Matsuhara
// CSE 122 AA
// Jan 1 2023
// Budgeter
// This class is a budgeter. It takes in the user's monthly income and daily
// expenses and then draws conclusions about the user's spending habits.
Method Comments¶
Each method in your program apart from the main method should have a corresponding method comment located directly above the method header. All method comments should include a description of the method’s behavior, parameters, and outcomes (does it return a value? does it manipulate a shared object?). You can think of them as mini-specs of a method!
One helpful acronym you might hear TAs mention is BERP! It stands for
- Behavior - Give a summary of what the method does; make sure to accurately cover all information and edge cases a reader may need to know about the method’s behavior, but avoid implementation details (see below)
- Exceptions - Document any exceptions the method might throw, including the specific type of exception and the circumstances that cause it
- Returns - Describe the return value for non-void methods, explicitly using the word “returns”
- Parameters - Mention each parameter along with a brief description of the value it holds
Avoiding Implementation Details¶
Something to keep in mind is that we want to avoid implementation details in method and class comments. We want to support abstraction by not mentioning anything private or technical. A client doesn’t need to know the inner workings of your code, so comments shouldn’t reveal anything beyond the outer behavior produced.
A few examples of implementation details include quoting lines of code, mentioning private fields, or explaining that you called a helper method to complete a sub-task. Someone reading your code can figure these things out just by looking at the method! Such details only serve as clutter to the reader.
Complete Comment Examples¶
// Calculates net profit or loss based on monthly income and daily spending
// and returns this value. Throws an IllegalArgumentException if the given
// income or spending are negative.
// 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){
if (income < 0 || spending < 0) {
throw new IllegalArgumentException();
}
return income - (spending * DAYS_IN_MONTH);
}
/* Calculates net profit or loss based on a given monthly income (int) and daily
spending (int) and then returns this value (int). Throws an IllegalArgumentException
if the given income or spending are less than zero. */
public static int calculateNetExpenses(int income, int spending){
if (income < 0 || spending < 0) {
throw new IllegalArgumentException();
}
return income - (spending * DAYS_IN_MONTH);
}
/**
* Calculates net profit or loss based on the given income and spending.
*
* @param income - the user's monthly income
* @param spending - the user's daily spending
* @throws IllegalArgumentException when income or spending are negative
* @return int - net profit or loss
*/
public static int calculateNetExpenses(int income, int spending){
if (income < 0 || spending < 0) {
throw new IllegalArgumentException();
}
return income - (spending * DAYS_IN_MONTH);
}
Incomplete Comment Examples¶
Inaccurate and Missing Specific Exception Type
// This method returns net profit or loss, which is calculated using the given income
// and spending amounts. There is an exception if income or spending are not positive.
public static int calculateNetExpenses(int income, int spending){
if (income < 0 || spending < 0) {
throw new IllegalArgumentException();
}
return income - (spending * DAYS_IN_MONTH);
}
This comment inaccurately implies that there will be an exception if income or spending are exactly equal to 0 (because 0 is “not positive”). It may seem like a tiny detail, but if you imagine a client using your program, it is important for them to know the exact situation that causes an exception!
It also lacks the specific type of exception that is being thrown (IllegalArgumentException, IllegalStateException, etc). This is important information for the reader to know!
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.
// Throws IllegalArgumentException if income or spending are negative.
public static int calculateNetExpenses(int income, int spending){
if (income < 0 || spending < 0) {
throw new IllegalArgumentException();
}
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 income and spending.
// Throws IllegalArgumentException if income or spending are negative.
public static int calculateNetExpenses(int income, int spending){
if (income < 0 || spending < 0) {
throw new IllegalArgumentException();
}
return income - (spending * DAYS_IN_MONTH);
}
This comment is missing a return comment and it is unclear whether income and spending are parameters, as there is no indication they are user-given. Additionally, rather than just listing out their names, there should also be a brief explanation of what those variables represent.
Inline Comments¶
Inline comments are optional comments written inside methods to explain tricky sections of code. They can either appear in between lines of code or at the end of a line. 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){
if (income < 0 || spending < 0) {
throw new IllegalArgumentException();
}
// multiply daily spending by days in month to get monthly spending
return income - (spending * DAYS_IN_MONTH);
}