1.8 Documentation with Comments

Why we use comments

Comments are text in source code ignored by the compiler, used to explain code to human readers. They help programmers document purpose, clarify tricky logic, and make code easier for others (and future you) to understand and maintain. Comments do not affect program execution or output.

Types of comments in Java

Java supports single-line comments using `//`, which comment out everything to the end of that line. It also supports multi-line (block) comments using `/* ... */`, which can span multiple lines and are closed with `*/`. Both are skipped entirely by the compiler.

Good commenting practice

Comments should explain why or what code does, not restate obvious syntax. Good places to comment: above a method to describe its purpose, near complex logic, or at the top of a file. Overusing comments on simple lines clutters code without adding value.

Key terms

Comment

Text in source code ignored by the compiler, used to explain code to human readers.

Single-line comment syntax

// comments out everything to the end of that line.

Multi-line comment syntax

/* ... */ comments out everything between the opening and closing symbols, even across multiple lines.

Do comments affect execution?

No — comments are ignored by the compiler and have no effect on program behavior or output.

Good comment usage

Use comments to explain purpose or complex logic; avoid over-commenting obvious code.

Try an AP-style question

Which comment style is used for Javadoc?

1. /* ... */
2. <!-- ... -->
3. /** ... */
4. // ...