Documentação com Comentários
Introduzido| English | Significado |
|---|---|
| comment/ˈkɒment/ | comentário |
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;
}
}

O Javadoc reconhece @param como uma tag de bloco quando ela é inserida após o texto de resumo na mesma linha.
Dificuldade 1/5 · Moedas 100 + pequeno bônus na primeira conclusão hoje
Uma tag de bloco inicia sua própria linha após espaço em branco opcional e um asterisco inicial opcional. Use o comentário multilinha 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.
Quando um programa Java executa, os comentários são...
Dificuldade 1/5 · Moedas 100 + pequeno bônus na primeira conclusão hoje
Comentários são para humanos — Java os ignora.
Qual começa um comentário de linha única em Java?
Dificuldade 1/5 · Moedas 100 + pequeno bônus na primeira conclusão hoje
// vai até o fim da linha; /* */ é um bloco.
Qual estilo de comentário ferramentas convertem em documentação de API?
Dificuldade 1/5 · Moedas 100 + pequeno bônus na primeira conclusão hoje
Javadoc /** */ com @param/@return gera docs de API.
Adicionar um comentário explicativo ao lado de uma fórmula ativa inalterada corrige seu cálculo.
Dificuldade 1/5 · Moedas 100 + pequeno bônus na primeira conclusão hoje
Falso: comentários explicativos não são declarações. Comentar uma declaração pode alterar o comportamento, mas isso altera qual código está ativo.
Bons comentários explicam O QUÊ, em vez de repetir o que o código obviamente faz.
Dificuldade 1/5 · Moedas 100 + pequeno bônus na primeira conclusão hoje
Comente a intenção, não o óbvio.
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.
Um comentário útil ou não?
Bons comentários explicam a intenção, não o óbvio. Classifique cada um.
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.
Dificuldade 1/5 · Moedas 100 + pequeno bônus na primeira conclusão hoje
The intended payment is 100−10=90. The misleading comment does not make the original expression calculate 90.
int x = 1; é seguido por // x = 5; em uma linha separada. Qual valor de x será impresso?
Dificuldade 2/5 · Moedas 140 + pequeno bônus na primeira conclusão hoje
A atribuição a 5 é excluída pelo comentário de linha única; x permanece 1.