Comments & Readable Code

Comments are notes for humans; the compiler ignores them completely.

// A single-line comment: everything after // is ignored.

/*
 * A block comment: everything between the markers is ignored,
 * even across many lines.
 */

/**
 * A documentation comment (javadoc): this one is *tool-visible* — the
 * javadoc tool turns these into HTML docs. Convention: start with a verb,
 * describe the contract.
 */
public class Notes {
    public static void main(String[] args) {
        System.out.println("Comments teach; they never run."); // trailing too
    }
}

Three habits that separate readable Java from noise:

1. Explain why, not what — // loop until the buffer drains teaches; // i plus one insults.
2. Prefer renaming over commenting. If a variable needs a comment to be understood, rename it: d → delayMillis.
3. Delete dead code instead of commenting it out. Version control remembers it; commented-out code rots and confuses every reader after you.

Java's official style is to use // freely for local notes, block comments for file headers or long explanations, and javadoc (/** ... */) for every public class and method — you will write javadoc when we build libraries in Module 5.

Next: errors — the compiler's and the JVM's — and how to read both.