Java Comments – A Beginner’s Guide with Examples
When writing Java programs, it’s not just about making the code work—it’s also about making it readable and maintainable. That’s where comments come in.
Comments in Java are notes you add to your code to explain what’s happening. They are ignored by the Java compiler, meaning they don’t affect how your program runs. Instead, they are for programmers (including your future self!) to understand the logic, purpose, or reasoning behind the code.
Why Use Comments?
- Improves readability – Makes the code easier to understand.
- Explains complex logic – Helps others (or you later) figure out why something was written a certain way.
- Temporary reminders – Used to mark sections of code that may need updates.
- Documentation – Provides detailed information about classes, methods, or variables.
Types of Comments in Java
Java provides three types of comments:
- Single-line comments
- Multi-line comments
- Documentation comments (Javadoc comments)
Let’s go through each one with examples.
1. Single-line Comments
Single-line comments start with //. Anything written after // on that line is ignored by the compiler.
Example:
public class SingleLineCommentExample {
public static void main(String[] args) {
// This prints a greeting message to the console
System.out.println(“Hello, World!”);
// The below line is commented out, so it won’t execute
// System.out.println(“This line is ignored”);
}
}
Use case: Best for short notes or quick explanations.
2. Multi-line Comments
Multi-line comments start with /* and end with */. They can span multiple lines, making them useful for longer explanations.
Example:
public class MultiLineCommentExample {
public static void main(String[] args) {
/*
* This is a multi-line comment.
* It is useful when you need to explain something
* in more detail or comment out large sections of code.
*/
System.out.println(“Java Multi-line Comments Example”);
/*
System.out.println(“This block of code is commented out.”);
System.out.println(“It will not run.”);
*/
}
}
Use case: Good for longer explanations or temporarily disabling multiple lines of code.
3. Documentation Comments (Javadoc Comments)
Documentation comments start with /** and end with */. These are special because they can be used to generate HTML documentation using the Javadoc tool.
Example:
/**
* The Calculator class provides methods
* to perform basic arithmetic operations.
*/
public class Calculator {
/**
* Adds two integers.
* @param a the first number
* @param b the second number
* @return the sum of a and b
*/
public int add(int a, int b) {
return a + b;
}
/**
* Subtracts two integers.
* @param a the first number
* @param b the second number
* @return the difference of a and b
*/
public int subtract(int a, int b) {
return a – b;
}
public static void main(String[] args) {
Calculator calc = new Calculator();
System.out.println(“Addition: ” + calc.add(10, 5));
System.out.println(“Subtraction: ” + calc.subtract(10, 5));
}
}
Use case: Best for creating API documentation for classes and methods.
Note: If you run the Javadoc tool on this file, it will generate professional HTML documentation describing your class and its methods.
Best Practices for Writing Comments
- Keep comments clear and concise.
- Use comments to explain why code is written a certain way, not just what it does.
- Avoid redundant comments (e.g., // prints Hello above System.out.println(“Hello”)).
- Update comments when code changes. Outdated comments can cause confusion.
- Use Javadoc comments for public classes and methods in professional projects.
Quick Recap
- Single-line (//) → Short explanations.
- Multi-line (/* … */) → Longer notes or disabling blocks of code.
- Documentation (/** … */) → Used with Javadoc for generating documentationa.
Final Thoughts
Comments are a simple yet powerful tool in Java programming. They make your code more readable, maintainable, and professional. Whether you’re working alone or in a team, writing good comments will save time and reduce confusion in the long run.