Java Comments — Single-Line, Multi-Line & Javadoc

// This entire line is a comment — compiler ignores it

int age = 21;   // This is an inline comment — code runs, comment is ignored

public class SingleLineCommentDemo {
    public static void main(String[] args) {

        // Step 1: Declare variables
        int price = 500;       // price in rupees
        int quantity = 3;       // number of items

        // Step 2: Calculate total
        int total = price * quantity;  // multiply price by quantity

        // Step 3: Display result
        System.out.println("Total: " + total);

        // System.out.println("Debug: " + price);  ← disabled for now
    }
}

/* This is a single-line block comment */

/*
 * This is a multi-line comment.
 * It can span as many lines as needed.
 * The leading * on each line is just a style convention — not required.
 */

public class MultiLineCommentDemo {

    /*
     * This method calculates the area of a rectangle.
     * Formula : Area = length × breadth
     * Both values must be positive integers.
     */
    static int calculateArea(int length, int breadth) {
        return length * breadth;
    }

    public static void main(String[] args) {

        int area = calculateArea(10, 5);
        System.out.println("Area: " + area);

        /*
         * The following block is temporarily disabled during testing.
         * Uncomment when the database connection is ready.
         *
         * DatabaseManager db = new DatabaseManager();
         * db.connect();
         * db.saveRecord(area);
         */
    }
}

/**
 * Represents a student enrolled in a course.
 *
 * <p>This class stores the student's name, roll number, and GPA.
 * It provides methods to calculate grade and check pass/fail status.</p>
 *
 * @author  Tech Sustainify
 * @version 1.0
 * @since   2026-01-01
 */
public class Student {
    // class body
}

/**
 * Calculates the sum of two integers.
 *
 * @param  a  the first integer operand
 * @param  b  the second integer operand
 * @return    the sum of {@code a} and {@code b}
 * @throws IllegalArgumentException if either value is negative
 */
public int add(int a, int b) {
    if (a < 0 || b < 0) {
        throw new IllegalArgumentException("Values must be non-negative");
    }
    return a + b;
}

/** The maximum number of students allowed per batch. */
public static final int MAX_STUDENTS = 60;

/**
 * The full name of the student.
 * Must not be null or empty.
 */
private String studentName;

/**
 * Manages a student's academic record.
 *
 * <p>Use {@link StudentManager} to create and manage multiple students.</p>
 *
 * @author  Tech Sustainify
 * @version 1.2
 * @since   2026-01-01
 */
public class Student {

    /** The maximum GPA on a 10-point scale. */
    public static final double MAX_GPA = 10.0;

    /** The full name of the student. */
    private String name;

    /** The student's GPA on a 10-point scale. */
    private double gpa;

    /**
     * Creates a new Student with the given name and GPA.
     *
     * @param name  the full name of the student; must not be {@code null}
     * @param gpa   the student's GPA; must be between 0.0 and {@value MAX_GPA}
     * @throws IllegalArgumentException if name is null or GPA is out of range
     */
    public Student(String name, double gpa) {
        if (name == null) throw new IllegalArgumentException("Name must not be null");
        if (gpa < 0 || gpa > MAX_GPA) throw new IllegalArgumentException("GPA out of range");
        this.name = name;
        this.gpa  = gpa;
    }

    /**
     * Returns the student's letter grade based on GPA.
     *
     * <ul>
     *   <li>9.0 – 10.0 → {@code 'O'} (Outstanding)</li>
     *   <li>7.5 – 8.9  → {@code 'A'}</li>
     *   <li>6.0 – 7.4  → {@code 'B'}</li>
     *   <li>Below 6.0  → {@code 'F'} (Fail)</li>
     * </ul>
     *
     * @return  the letter grade as a {@code char}
     * @since   1.1
     */
    public char getGrade() {
        if      (gpa >= 9.0) return 'O';
        else if (gpa >= 7.5) return 'A';
        else if (gpa >= 6.0) return 'B';
        else                 return 'F';
    }

    /**
     * @deprecated Use {@link #getGrade()} instead. This method will be
     *             removed in version 2.0.
     * @return grade as a String
     */
    @Deprecated
    public String getGradeOld() {
        return String.valueOf(getGrade());
    }
}

# Step 1 — Navigate to your source folder
cd /path/to/your/project/src

# Step 2 — Generate docs into a 'docs' folder
javadoc -d docs -author -version Student.java

# Step 3 — Open the generated documentation
# On Windows:
start docs/index.html

# On macOS:
open docs/index.html

# On Linux:
xdg-open docs/index.html

// ❌ BAD — states the obvious, adds no value
int age = 21;  // set age to 21

// ✅ GOOD — explains non-obvious business rule
int age = 21;  // minimum age to open a bank account per RBI guidelines


// ❌ BAD — cryptic without explanation
if (x > 86400) { reset(); }

// ✅ GOOD — explains the magic number
// 86400 = seconds in a day; reset session after 24 hours
if (x > 86400) { reset(); }


// ✅ GOOD — TODO for pending work
// TODO: replace this linear search with binary search for large datasets
for (int i = 0; i < arr.length; i++) { ... }

// ✅ GOOD — FIXME for known bugs
// FIXME: throws NullPointerException when user is not logged in
String username = user.getName();

/*
 * Attempting to comment out a block that contains another block comment:
 *
 * int x = calculate(); /* uses old formula */
 *                                           ↑
 * Java sees THIS as the end of the outer /* comment
 * Everything after this is treated as live code → compile error!
 */

// ✅ Correct way to comment out code that has /* */ inside:
// int x = calculate(); /* uses old formula */

/**
 * Represents a simple bank account with deposit and withdrawal operations.
 *
 * <p>This class demonstrates all three Java comment types in a real-world context.</p>
 *
 * @author  Tech Sustainify
 * @version 1.0
 * @since   2026-01-01
 */
public class BankAccount {

    /** Minimum balance required to keep the account active (in rupees). */
    public static final int MIN_BALANCE = 500;

    /** The current balance of the account. */
    private double balance;

    /** The name of the account holder. */
    private String holderName;

    /**
     * Creates a new BankAccount with an initial deposit.
     *
     * @param holderName    the name of the account holder; must not be null
     * @param initialAmount the opening balance; must be >= {@value MIN_BALANCE}
     * @throws IllegalArgumentException if initial amount is below minimum balance
     */
    public BankAccount(String holderName, double initialAmount) {
        // Validate the initial deposit before setting
        if (initialAmount < MIN_BALANCE) {
            throw new IllegalArgumentException(
                "Opening balance must be at least ₹" + MIN_BALANCE
            );
        }
        this.holderName = holderName;
        this.balance    = initialAmount;
    }

    /**
     * Deposits the given amount into the account.
     *
     * @param  amount  the amount to deposit; must be positive
     * @return         the updated balance after deposit
     * @throws IllegalArgumentException if amount is zero or negative
     */
    public double deposit(double amount) {
        /*
         * Business rule: deposits must be positive.
         * A zero deposit is meaningless and negative would be equivalent
         * to a withdrawal — which has its own method.
         */
        if (amount <= 0) {
            throw new IllegalArgumentException("Deposit amount must be positive");
        }
        balance += amount;
        return balance;  // return updated balance for confirmation
    }

    /**
     * Withdraws the given amount from the account.
     *
     * @param  amount  the amount to withdraw; must be positive
     * @return         the updated balance after withdrawal
     * @throws IllegalArgumentException if amount exceeds available balance
     */
    public double withdraw(double amount) {
        // Ensure withdrawal does not drop below minimum balance
        if (balance - amount < MIN_BALANCE) {
            throw new IllegalArgumentException(
                "Insufficient funds. Minimum balance of ₹" + MIN_BALANCE + " required."
            );
        }
        balance -= amount;
        return balance;
    }

    /**
     * Returns a formatted account summary string.
     *
     * @return account summary with holder name and current balance
     */
    public String getSummary() {
        return String.format("Account Holder: %s | Balance: ₹%.2f", holderName, balance);
    }

    public static void main(String[] args) {

        // Create a new account with ₹10,000 opening balance
        BankAccount account = new BankAccount("Rahul Sharma", 10000);

        // Perform transactions
        account.deposit(5000);    // add ₹5,000
        account.withdraw(3000);   // remove ₹3,000

        /*
         * TODO: integrate with the SMS notification service
         * to send transaction alerts after each deposit/withdrawal.
         */

        // Print the final account summary
        System.out.println(account.getSummary());
    }
}