Java Comments - Complete Guide
Introduction to Java Comments
Comments in Java are notes within the source code that are ignored by the compiler. They help developers explain logic, provide documentation, or temporarily disable code without affecting execution.
Java supports three kinds of comments: single-line (//), multi-line (/* */), and documentation (/** */). Each has a specific use case and syntax.
Single-Line Comments
Single-line comments start with // and continue to the end of the line. They are best for short explanations or disabling one line of code.
public class SingleLineComments {
public static void main(String[] args) {
// Declare and initialize variable
int age = 25; // store age
// System.out.println("This line is disabled");
double total = calculateTotal(100, 0.1); // apply 10% discount
System.out.println("Final total: " + total);
}
// Method applies discount
public static double calculateTotal(double amount, double discount) {
return amount - (amount * discount);
}
}Multi-Line Comments
Multi-line comments begin with /* and end with */. They are used for longer explanations or temporarily disabling blocks of code.
public class MultiLineComments {
/*
* Example: multi-line comment spanning several lines.
* Useful for detailed notes.
*/
public static void main(String[] args) {
/*
This block calculates an average.
Disabled temporarily for debugging.
double avg = (85 + 92 + 78) / 3.0;
char grade = calculateGrade(avg);
System.out.println("Average: " + avg + ", Grade: " + grade);
*/
System.out.println("Program still runs even with large blocks commented out.");
}
/*
Determines grade based on average.
*/
public static char calculateGrade(double average) {
if (average >= 90) return 'A';
else if (average >= 80) return 'B';
else if (average >= 70) return 'C';
else if (average >= 60) return 'D';
else return 'F';
}
}Documentation Comments (Javadoc)
Documentation comments (/** */) are used to create external documentation with the Javadoc tool. They can include tags for structured information.
/**
* Represents a simple BankAccount.
* Demonstrates Javadoc usage.
*
* @author John Doe
* @version 1.0
* @since 2024
*/
public class BankAccount {
private double balance;
/**
* Constructs a BankAccount with initial balance.
* @param initialBalance starting balance
* @throws IllegalArgumentException if initialBalance < 0
*/
public BankAccount(double initialBalance) {
if (initialBalance < 0) {
throw new IllegalArgumentException("Balance cannot be negative");
}
this.balance = initialBalance;
}
/**
* Deposits money.
* @param amount to deposit
* @return new balance
* @throws IllegalArgumentException if amount < 0
*/
public double deposit(double amount) {
if (amount < 0) throw new IllegalArgumentException("Negative deposit not allowed");
balance += amount;
return balance;
}
/**
* Withdraws money.
* @param amount to withdraw
* @return new balance
* @throws IllegalArgumentException if amount < 0 or exceeds balance
*/
public double withdraw(double amount) {
if (amount < 0) throw new IllegalArgumentException("Negative withdrawal not allowed");
if (amount > balance) throw new IllegalArgumentException("Insufficient funds");
balance -= amount;
return balance;
}
/**
* Returns balance.
* @return current balance
*/
public double getBalance() {
return balance;
}
}Common Javadoc Tags
| Tag | Description | Example |
|---|---|---|
| @author | Specifies author | @author John |
| @version | Indicates version | @version 1.2 |
| @since | Introduced version | @since JDK 1.8 |
| @param | Describes method parameter | @param name user name |
| @return | Describes return value | @return true if success |
| @throws | Documents thrown exception | @throws IOException if file missing |
| @see | Links to related item | @see OtherClass |
| @deprecated | Marks method deprecated | @deprecated use newMethod() |
Commenting Best Practices
- ✅ Explain WHY, not WHAT
- ✅ Keep comments updated
- ✅ Use Javadoc for public APIs
- ✅ Avoid redundant comments
- ✅ Mark TODOs or future improvements
- ✅ Write clear and concise notes
- ✅ Maintain consistent style
- ✅ Remove old commented-out code
When to Use Comments
Effective comment strategy includes:
• Complex algorithms: explain logic
• Business rules: document reasoning
• API documentation: use Javadoc for public classes and methods
• Debugging: temporarily disable code
• TODO notes: mark pending work
• Warnings: highlight potential issues