Java Comments

Welcome to The Coding College, your go-to resource for mastering programming concepts! In this guide, we’ll explore Java comments, an essential feature that makes your code readable, maintainable, and professional. Whether you’re a beginner or an experienced developer, understanding comments is a key part of writing effective code.

What Are Comments in Java?

Comments are non-executable lines of text in your code. They are used to explain what your code does, making it easier to understand for others (and yourself). Java ignores these lines during execution.

Why Use Comments?

  • Improve Readability: Explain complex logic or algorithms.
  • Debugging Assistance: Temporarily disable code for testing.
  • Collaboration: Help teams understand your code better.

Types of Comments in Java

Java supports three types of comments:

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

1. Single-Line Comments

Single-line comments start with // and apply to the line they are on.

Syntax:

// This is a single-line comment

Example:

public class SingleLineComments {
    public static void main(String[] args) {
        // Printing a welcome message
        System.out.println("Welcome to The Coding College!");
    }
}

Output:

Welcome to The Coding College!

2. Multi-Line Comments

Multi-line comments start with /* and end with */. They are used to comment out multiple lines of code or provide detailed explanations.

Syntax:

/* 
This is a multi-line comment.
It spans over multiple lines.
*/

Example:

public class MultiLineComments {
    public static void main(String[] args) {
        /* 
         Printing two messages.
         The second message is about Java.
        */
        System.out.println("Hello, World!");
        System.out.println("Java is powerful!");
    }
}

Output:

Hello, World!  
Java is powerful!

3. Documentation Comments

Documentation comments (/** ... */) are used to generate API documentation using the javadoc tool. These comments are placed before classes, methods, or fields and follow a specific format.

Syntax:

/**
 * Description of the class, method, or field.
 */

Example:

/**
 * This class demonstrates Java comments.
 */
public class DocumentationComments {
    /**
     * This method prints a greeting message.
     */
    public static void main(String[] args) {
        System.out.println("Learning Java with The Coding College!");
    }
}

To generate documentation, run:

javadoc DocumentationComments.java

Common Uses of Comments

Explaining Code Logic

public class ExplainLogic {
    public static void main(String[] args) {
        int a = 5, b = 10;

        // Adding two numbers
        int sum = a + b;

        // Printing the result
        System.out.println("Sum: " + sum);
    }
}

Disabling Code During Debugging

public class DebuggingExample {
    public static void main(String[] args) {
        // System.out.println("This line is disabled.");
        System.out.println("Debugging in progress.");
    }
}

Marking TODOs

// TODO: Add user input functionality
public class TodoExample {
    public static void main(String[] args) {
        System.out.println("Feature under development...");
    }
}

Best Practices for Comments

  • Be Clear and Concise: Avoid overly detailed comments. 
// Calculates the sum of two integers
int sum = a + b;
  • Avoid Obvious Comments: 
// Incrementing i
i++;  // This comment is unnecessary.
  • Update Comments Regularly: Ensure comments match the latest code logic.
  • Use Documentation Comments for Public APIs: 
/**
 * Calculates the square of a number.
 * @param num The number to square.
 * @return The squared value.
 */
public int square(int num) {
    return num * num;
}

Practice Exercise

  • Add single-line comments to explain the following code: 
int x = 10;
int y = 20;
System.out.println("Sum: " + (x + y));
  • Use multi-line comments to describe the purpose of a program that calculates the area of a circle.
  • Write a method to reverse a string and add documentation comments for it.

Conclusion

Comments are a vital tool in any programmer’s toolkit. They help create understandable, maintainable, and professional-quality code. By mastering the use of comments, you ensure your code speaks not just to computers but to humans as well.

Explore more Java tutorials and tips at TheCodingCollege.com, and take your coding journey to the next level!

Leave a Comment