Documentation with Comments
| English | Chinese | Pinyin |
|---|---|---|
| comment | 注释 | zhù shì |
Notes for humans
- A comment 注释 is text in your code that Java ignores when running.
- Comments are written for people — to explain what and why.
- They never change what the program does; they only help readers understand it.
- Good comments make code easier to maintain (including by future-you).
The three comment styles
- Single-line:
// this runs to the end of the line. - Multi-line (block):
/* everything between these runs across lines */. - Javadoc:
/** … */— a special block the tools turn into API documentation. - Pick the style that fits the note's length and purpose.
Javadoc documents your methods
- Javadoc
/** … */comments sit just above a method or class. - Special tags describe the interface:
@param(a parameter),@return(the result). - Tools read these to generate the API documentation other programmers rely on.
- Writing Javadoc turns your own code into a proper, documented library.
Comment the why, not the obvious
- Don't restate what the code plainly says (
x = x + 1; // add oneis noise). - Do explain why, tricky logic, assumptions, or the units of a value.
- Comments that drift out of date are worse than none — keep them accurate.
- The best code reads clearly on its own; comments fill the remaining gaps.
A useful comment or not?
Good comments explain intent, not the obvious. Sort each one.
Comments are ignored by the compiler — they never affect behavior. Commenting out a line (// x = 5;) makes Java skip it, a handy debugging trick, but a comment can't fix a logic bug. And prefer comments that explain why, not ones that restate the obvious — a stale or redundant comment misleads more than it helps.
A well-documented method header:
/** Returns the area of a circle. @param r the radius. @return the area. */public double area(double r) { return Math.PI * r * r; }- The Javadoc tells a caller exactly what to pass and what comes back.
A comment is text Java ignores, written to explain code to people. Styles: // single-line, /* */ block, and /** */ Javadoc (with @param/@return) that tools turn into API docs. Comment the why, not the obvious, and keep comments accurate — they never change behavior.
When a Java program runs, comments are...
Comments are for humans — Java ignores them.
Which starts a single-line comment in Java?
// runs to the end of the line; /* */ is a block.
Which comment style do tools turn into API documentation?
Javadoc /** */ with @param/@return generates API docs.
Adding a comment can fix a logic error in the program.
Comments never change behavior — they can't fix bugs.
Good comments explain WHY, rather than restating what the code obviously does.
Comment the intent, not the obvious.