Documentación con Comentarios
Introducido| English | Significado |
|---|---|
| comment/ˈkɒment/ | comentario |
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 reconoce @param como una etiqueta de bloque cuando está incrustada después del texto de resumen en la misma línea.
Dificultad 1/5 · 100 monedas + un pequeño bono en el primer intento de hoy
Una etiqueta de bloque comienza en su propia línea después de espacio en blanco opcional y una estrella inicial opcional. Use el comentario multilínea mostrado.
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.
Cuando se ejecuta un programa en Java, los comentarios son...
Dificultad 1/5 · 100 monedas + un pequeño bono en el primer intento de hoy
Los comentarios son para humanos — Java los ignora.
¿Cuál inicia un comentario de una sola línea en Java?
Dificultad 1/5 · 100 monedas + un pequeño bono en el primer intento de hoy
// se extiende hasta el final de la línea; /* */ es un bloque.
¿Qué estilo de comentario las herramientas convierten en documentación de API?
Dificultad 1/5 · 100 monedas + un pequeño bono en el primer intento de hoy
Javadoc /** */ con @param/@return genera documentación de API.
Añadir un comentario explicativo junto a una fórmula activa inalterada repara su cálculo.
Dificultad 1/5 · 100 monedas + un pequeño bono en el primer intento de hoy
Falso: los comentarios explicativos no son sentencias. Comentar una sentencia puede cambiar el comportamiento, pero eso cambia qué código está activo.
Los buenos comentarios explican el PORQUÉ, en lugar de reafirmar lo que el código obviamente hace.
Dificultad 1/5 · 100 monedas + un pequeño bono en el primer intento de hoy
Comenta la intención, no lo obvio.
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 comentario útil o no?
Los buenos comentarios explican la intención, no lo obvio. Ordena cada uno.
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.
Dificultad 1/5 · 100 monedas + un pequeño bono en el primer intento de hoy
The intended payment is 100−10=90. The misleading comment does not make the original expression calculate 90.
int x = 1; es seguido por // x = 5; en una línea separada. ¿Qué valor de x se imprime?
Dificultad 2/5 · 140 monedas + un pequeño bono en el primer intento de hoy
La asignación a 5 está excluida por el comentario de una sola línea; x permanece 1.