Documentation with Comments
Introduced| English |
|---|
| comment/ˈkɒment/ |
A comment does not repair an active formula
- For price 100,
total = price * 10 / 100;calculates 10 even if a comment 注释 says “amount paid after ten percent off”. Editing that explanation does not make the expression calculate 90. - Change the active expression to
price * 90 / 100to calculate the intended payment in this whole-number example. Comments can reveal an intended policy; verify the code implements it.
Identify text that is excluded from code
//starts a comment ending at the line break./*starts a block comment ending at the next*/; block comments do not nest. Delimiters inside string literals are text, so"https://example.com"does not start a comment.- Comment text is not executed as Java statements. Adding a separate explanation leaves the active expression unchanged; placing
//before an active assignment removes that assignment from the compiled code and can change behavior.
Put Javadoc tags on separate lines
- A
/** ... */documentation comment immediately before a declaration can be processed by Javadoc. Its summary explains the operation; block tags such as@paramand@returnstart their own lines after optional whitespace and*. - The complete class below documents a non-negative radius and returns its circle area. The tags describe inputs, outputs and a rejected input; a comment alone does not enforce the precondition, so the method explicitly checks negative radii.
/** Circle-area calculations for finite radii. */
public class AreaDoc {
/**
* Returns the area of a circle for a finite radius.
* @param r the non-negative radius
* @return the area in squared radius units
* @throws IllegalArgumentException if r is negative
*/
public static double area(double r) {
if (r < 0) {
throw new IllegalArgumentException("Negative radius");
}
return Math.PI * r * r;
}
}
Javadoc recognizes @param as a block tag when it is embedded after summary text on the same line.
A block tag starts its own line after optional whitespace and an optional leading star. Use the shown multiline comment.
Explain the decision a reader cannot see
- A useful discount comment might state “payment is 90% of the listed price; this exercise uses whole-number prices”. This explains policy and assumptions, while
// multiply by 90merely repeats an operation. - A summary of a public method is useful even when its body is short: callers need its contract without studying the implementation. Prefer explanations that supply missing context rather than declaring every descriptive comment redundant.
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 an explanatory comment beside an unchanged active formula repairs its calculation.
False: explanatory comments are not statements. Commenting out a statement can change behavior, but that changes which code is active.
Good comments explain WHY, rather than restating what the code obviously does.
Comment the intent, not the obvious.
Check documentation against implementation
- Suppose the comment promises that negative radii are rejected, but the guard is deleted. The documentation is now false even though it still generates successfully; test the negative input as well as an ordinary radius.
- When behavior changes, update the implementation, its checks and its documentation together. Generating an API page verifies documentation syntax, not the truth of every claim in it.
/** Returns an area. @param r radius @return area */ does not put the block tags at the required starts of lines. Use the multiline form above, then inspect the generated parameter and return sections. Ordinary explanatory comments are not executable repairs.
A useful comment or not?
Good comments explain intent, not the obvious. Sort each one.
Predict a commented-out assignment
- Start with
int x = 1;. With activex = 5;, printing x gives 5; replacing that line with// x = 5;prints 1. Changing which statements are active differs from adding a note beside an unchanged statement. - Review three questions separately: is the active calculation correct, does the comment accurately explain it, and are the Javadoc tags parsed into their intended sections? A successful compile does not answer all three.
Comments explain code to readers. Delimiters can exclude statements, while notes beside active code do not fix calculations. Javadoc block tags begin on separate lines; keep the documented contract consistent with the implementation.
For a price of 100, type the amount paid after a ten percent discount.
The intended payment is 100−10=90. The misleading comment does not make the original expression calculate 90.
int x = 1; is followed by // x = 5; on a separate line. What value of x is printed?
The assignment to 5 is excluded by the single-line comment; x stays 1.