Documentation avec Commentaires
Introduit| English | Sens |
|---|---|
| comment/ˈkɒment/ | commentaire |
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 reconnaît @param comme une balise de bloc lorsqu'elle est insérée après le texte de résumé sur la même ligne.
Difficulté 1/5 · 100 pièces + un petit bonus lors de la première réussite aujourd'hui
Une balise de bloc commence sa propre ligne après un espace facultatif et une étoile facultative. Utilisez le commentaire multiligne illustré.
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.
Lorsqu'un programme Java s'exécute, les commentaires sont...
Difficulté 1/5 · 100 pièces + un petit bonus lors de la première réussite aujourd'hui
Les commentaires sont pour les humains — Java les ignore.
Quel élément commence un commentaire sur une seule ligne en Java ?
Difficulté 1/5 · 100 pièces + un petit bonus lors de la première réussite aujourd'hui
// va jusqu'à la fin de la ligne ; /* */ est un bloc.
Quel style de commentaire les outils transforment-ils en documentation API ?
Difficulté 1/5 · 100 pièces + un petit bonus lors de la première réussite aujourd'hui
Javadoc /** */ avec @param/@return génère la doc API.
Ajouter un commentaire explicatif à côté d'une formule active inchangée répare son calcul.
Difficulté 1/5 · 100 pièces + un petit bonus lors de la première réussite aujourd'hui
Faux : les commentaires explicatifs ne sont pas des instructions. Commenter une instruction peut modifier le comportement, mais cela modifie le code qui est actif.
De bons commentaires expliquent POURQUOI, plutôt que de répéter ce que le code fait manifestement.
Difficulté 1/5 · 100 pièces + un petit bonus lors de la première réussite aujourd'hui
Commentez l'intention, pas l'évidence.
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.
Un commentaire utile ou non ?
De bons commentaires expliquent l'intention, pas l'évidence. Trier chacun.
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.
Difficulté 1/5 · 100 pièces + un petit bonus lors de la première réussite aujourd'hui
The intended payment is 100−10=90. The misleading comment does not make the original expression calculate 90.
int x = 1; est suivi par // x = 5; sur une ligne séparée. Quelle valeur de x sera imprimée ?
Difficulté 2/5 · 140 pièces + un petit bonus lors de la première réussite aujourd'hui
L'assignation à 5 est exclue par le commentaire sur une seule ligne ; x reste 1.