Best Practices

You now know both types of comments in Java: // and /* */. But just as important as the syntax is knowing when and how to use comments effectively. Here are the most important rules for good comments.

Rule 1: Explain the WHY, not the WHAT. Good code is often already self-explanatory — what it does is visible from the code itself. A comment is usually only helpful when it explains the reason behind a decision.

// Bad: just repeats the code
// prints Hello
System.out.println("Hello");

// Good: explains the reason
// Greeting for new users on the app's first launch
System.out.println("Hello");

The comment "// prints Hello" above System.out.println("Hello"); is an example of a good comment.

Rule 2: Keep comments up to date. When the code changes but the comment doesn't, you end up with an outdated comment. An outdated comment is often worse than no comment at all — it misleads others (and yourself).

// Prints the user's first name
System.out.println("Welcome back!");

A comment that no longer matches the current code is called ____.

Rule 3: Don't over-comment. If every single, obvious line gets its own comment, the code becomes more cluttered instead of clearer. Use comments purposefully: to mark sections or to explain truly tricky parts.

// Bad: a comment for every single, obvious line
public class Main {
    public static void main(String[] args) {
        // prints text
        System.out.println("Hello");
    }
}

// Good: a comment marks only the important section
public class Main {
    public static void main(String[] args) {
        // --- Greeting ---
        System.out.println("Hello!");
        System.out.println("Glad you're here.");
    }
}

When is a comment most useful?