Comments

A school program needs reliable data and clear rules. Comments explain why instructions exist without executing those words. A school marks calculation still runs normally when you add a note beside it.

Every great codebase tells a story — not just through what it does, but through how clearly it’s explained.

Comments don’t affect how a program runs. Instead, they help other people (and your future self) understand, maintain, and debug the code more easily.

You can use comments to:

• Clarify complex logic
• Mark sections for future improvement
• Disable parts of the code temporarily
• Generate documentation (JavaDoc)

Java supports three main types of comments:

1. Single-line Comments
2. Multi-line Comments
3. Documentation Comments

These are used for short explanations or notes.

// This is a single-line comment
System.out.println("Hello, World!"); // Print statement

Here is a simple example, where we use single line comments when doing addition of two numbers.

public class AdditionExample {
    public static void main(String[] args) {
        // Declare two integer variables and assign values
        int num1 = 10;
        int num2 = 20;

        // Add the two numbers and store the result in sum
        int sum = num1 + num2;

        // Print the result to the console
        System.out.println("The sum is: " + sum);
    }
}

Hello, World!

Explanation: The lines starting with // are ignored by the compiler. Only the System.out.println() line executes and prints the output.

Multi-line Comments are used when you want to explain something in more than one line. These can also be used to temporarily disable blocks of code during testing or debugging.

/* This is a multi-line comment.
   It can span several lines.
   Useful for detailed notes or explanations. */
System.out.println("Multi-line comment demo");

Multi-line comment demo

Note: Everything between /* and */ is ignored by the compiler.

Specially formatted comments used to generate official documentation. These comments are placed just before class, method, or field declarations.

/**
 * This class demonstrates JavaDoc comments.
 * @author Mallikarjuna
 * @version 1.0
 */
public class Example {

    /**
     * This method prints a greeting.
     * @param name The name to greet
     */
    public void greet(String name) {
        System.out.println("Hello, " + name);
    }
}

Usage Tip: Use the javadoc tool to generate HTML documentation from JavaDoc comments:

javadoc Example.java

• Write comments that add value—don't repeat the code.
• Keep them up-to-date. Outdated comments can mislead developers.
• Use comments to explain "why" more than "what".
• Avoid cluttering your code with excessive comments—clarity is key.

• Using comments to excuse bad code. Refactor instead.
• Leaving debug comments in production code.
• Overusing JavaDoc for private/internal methods that don’t need documentation.

Comments do not replace clear code. Text inside a quoted string is data, even when it contains comment-like characters.

Before running this Java program, write down each line you expect to see. Identify the value, branch, object or exception responsible for each line. Then explain whether the following assumption is valid: Comments do not replace clear code.

Java 17 · Main.java · complete practice program

public class Main  {
  public static void main(String[] args)  {
    int marks = 72;
    /* marks out of 100 */ System.out.println(marks);
  }
}

Now change one thing: Remove the comment while keeping the instructions. Predict the new behavior before checking the worked variation.

Java 17 · Main.java · source repeated for this answer

public class Main  {
  public static void main(String[] args)  {
    int marks = 72;
    /* marks out of 100 */ System.out.println(marks);
  }
}

Expected output

72

Comments explain why instructions exist without executing those words. A school marks calculation still runs normally when you add a note beside it.

Comments do not replace clear code. Text inside a quoted string is data, even when it contains comment-like characters.

Run with javac Main.java, then java Main. The declaration of Main names the class; main starts the example, and println writes a complete output line.

Worked variation: Remove the comment while keeping the instructions. Explain why the output is unchanged.

Comments explain why instructions exist without executing those words. A school marks calculation still runs normally when you add a note beside it. Comments do not replace clear code. Text inside a quoted string is data, even when it contains comment-like characters.

Related explanations: Java Variables, Java If Statement - Syntax and Examples, Java Class - Blueprint of Objects, Exceptions in Java Introduction.

Supporting documentation: Official Java learning guide and Java 17 language specification.