Writing Comments in Java: A Beginner's Guide

In today’s blog, we’re going to look at how comments work in Java. Comments are an essential part of programming because they let you explain your code without affecting how it runs. They’re like little notes to yourself or to anyone else reading your code. Whether you’re writing a quick reminder, documenting a method, or disabling a section of code during testing, Java gives you multiple ways to add comments. Let’s explore how each one works.

Section 1 - The Why Behind Comments:

Comments in Java (and most programming languages) are not executed by the program; they are ignored, making them useful in taking notes or explaining how or why the code is there. You might be wondering why comments are necessary at all when it comes to programming. Here are some reasons you should consider adding comments to your program;

Clarity for yourself: What makes sense today might confuse you in a month. Comments remind you why you wrote the code a certain way.

Team collaboration: If you’re working with others, comments make your code readable and understandable for teammates.

Maintenance: When bugs show up, comments help track logic quickly, saving debugging time.

Documentation: They explain the purpose of functions, classes, and methods, making it easier to generate proper documentation later.

Learning tool: If someone new (or even you later) is learning from your code, comments make the thought process visible.

Future-proofing: When you revisit your project months or years later, comments help you pick up right where you left off.

Section 2 - The Type Of Comments In Java:

In Java, there are different types of comments you could use based on the purpose. They are as follows;

• Single line comments(//): Single line comments are denoted with the symbol, '//'. You resort to using single-line comments when you want to comment on a statement that ends on a line. For Example;
  System.out.println("We will not use 'Hello, World!'"); // prints message. You could also temporarily disable a line of code by commenting that part of the code out. This is done by placing the single-line comment right before the line of code. For example: // System.out.println("This line is disabled temporarily");. This comment does not disable the code right below it, hence it only works on the code written on the same line as the single-line comment.

• Multi-line Comments(/*...*/): Multi-line comments are denoted using the symbol, /*....*/. You resort to multi-line comments when you want to comment multiple blocks of code, or you want to write comments that will span more than just a line. For example;
  

/*
This is a longer comment
that spans multiple lines
*/

NOTE: Multi-line comments do not nest. Trying this will break the loop at some point.

/* 
System.out.println("Hello"); 
/* This breaks */
*/

• Documentation Comments(/** ... */): These are special comments used to generate documentation automatically with Javadoc. For Example;

/**
 * This is the first sample program in Core Java
 * @version 1.01 1997-03-22
 * @author Gary Cornell
 */
public class FirstSample {
    public static void main(String[] args) {
        System.out.println("We will not use 'Hello, World!'");
    }

A Couple Of Additional Info

Apart from regular comments, Java also provides Javadoc comments. These are special comments that start with /** and end with */. They are mainly used to describe classes, methods, and fields in a way that allows you to automatically generate documentation for your code.
Example:

/**
 * This is a simple HelloWorld program.
 * @author Cal
 * @version 1.0
 */

public class HelloWorld {
    /**
     * Prints "Hello, World!" to the terminal.
     * @param args unused
     */
    public static void main(String[] args) {
        System.out.println("Hello, World!");
    }
}

Generating Documentation
To generate documentation from these comments:
Save your file (e.g., HelloWorld.java).
Open your terminal/command prompt and navigate to the file’s location.
Run:
javadoc HelloWorld.java
Open the generated index.html in your browser to see the documentation.
👉 You can also use:
javadoc -d docs HelloWorld.java
to store the docs neatly in a folder called docs/.
This is how the official Java API documentation is created!

But why document your code?

Improves Readability:
Documentation helps others (and your future self) quickly understand what your code is doing without having to decode every single line.

Saves Time in the Future:
When you revisit your project weeks or months later, well-written comments save you from wasting time trying to remember your logic.

Helps Collaboration:
If you’re working in a team, documentation ensures everyone understands the purpose of classes, methods, and variables.

Provides Context Beyond the Code:
Sometimes code alone doesn’t explain why you made a particular decision, documentation fills in that gap.

Enables Auto-Generated Documentation:
With Javadoc, your comments can turn into professional HTML docs, making your project look polished and easier for others to use.

Reduces Errors:
Clear documentation discourages misuse of methods or misunderstanding of expected inputs/outputs.