Comentários em Java

Comentários são textos que o compilador ignora. Eles existem para as pessoas que lêem o código-fonte. Java possui três tipos — linha única, multi-linha e Javadoc — cada um com seu próprio papel.

Este capítulo aborda a sintaxe dos três estilos, como gerar documentação HTML a partir do Javadoc e — igualmente importante — quando um comentário vale a pena ser escrito e quando ele apenas adiciona ruído. Se você é novo na estrutura do Java, leia Java Syntax primeiro.

Comentários de linha única — //

Tudo desde // até o final da linha é um comentário:

int total = price * quantity;   // running subtotal in cents
// totalPrice was renamed to total in 2024-05

Use-os para notas curtas ao lado de uma linha de código ou para desativar temporariamente uma linha durante a depuração.

Comentários multi-linha — /* ... */

Tudo entre /* e */ é ignorado, mesmo que ocupe várias linhas:

/*
 * The default leading-asterisk style isn't required, but most IDEs
 * insert it automatically and it keeps long comments readable.
 *
 * This block is parsed as a single comment.
 */
int retries = 3;

Comentários multi-linha também podem aparecer de forma inline:

int width = 800 /* pixels */;

Você não pode aninhá-los: /* outer /* inner */ */ termina no primeiro */, deixando caracteres */ soltos que causam falha na compilação. Para "comentar" um bloco que já contém /* … */, use // em cada linha (sua IDE tem um atalho para isso — geralmente Ctrl+/ / Cmd+/).

Comentários Javadoc — /** ... */

Comentários Javadoc começam com /** (nota: duas estrelas) e são lidos pela ferramenta javadoc para gerar documentação HTML:

/**
 * Calculates the area of a rectangle.
 *
 * @param width  the rectangle's width in cm; must be non-negative
 * @param height the rectangle's height in cm; must be non-negative
 * @return the area in square centimeters
 */
public static double area(double width, double height) {
    return width * height;
}

Comentários Javadoc são colocados imediatamente acima da classe, método ou campo que descrevem. A primeira frase se torna a linha de resumo na documentação gerada.

As tags mais úteis:

• @param name description — uma por parâmetro
• @return description — o que o método retorna
• @throws ExceptionClass description — quando o método lança uma exceção
• @see ClassOrLink — referência cruzada
• @since 1.5 — quando esta API foi adicionada
• @deprecated reason — desencoraja o uso posterior (o compilador também avisa)

Toda a biblioteca padrão é documentada com Javadoc; as IDEs a leem para alimentar suas dicas de ferramentas.

Gerando a documentação HTML

A ferramenta javadoc é fornecida com o JDK. Aponte-a para seus arquivos-fonte (ou pacotes) e ela gera um site HTML navegável:

javadoc -d docs Greeter.java

A flag -d docs escolhe o diretório de saída. Abra docs/index.html em um navegador para ver as páginas geradas — o mesmo layout que você obtém na documentação oficial da Oracle, construído a partir dos comentários acima de cada classe e método.

Quando comentar, quando não comentar

Um bom código é sua própria documentação. Comentários que repetem o que o código já mostra apenas adicionam ruído e ficam desatualizados rapidamente:

// BAD: increment counter
counter++;

// BAD: returns the user's name
public String getName() { return name; }

Os comentários têm valor quando explicam o porquê, não o o quê:

// Stripe rejects amounts smaller than $0.50 — round up so we never
// hit the minimum-charge error.
int chargeCents = Math.max(50, computed);

Ou quando documentam uma restrição não óbvia:

// Caller must hold the writeLock; this method itself does no locking.
private void persist(Order o) { ... }

Para APIs públicas, escreva Javadoc. Para código interno, escreva apenas os comentários que ajudam o próximo leitor a tomar uma decisão.

Uma demonstração

O compilador remove os três estilos de comentário antes de gerar o bytecode, portanto eles têm custo zero em tempo de execução.

O que vem a seguir

Agora que você sabe documentar código, passe para os blocos de construção que ele descreve:

• Java Variables — declaração, inicialização e escopo.
• Java Syntax — instruções, blocos e as regras que o compilador aplica.
• Java Hello World — o programa mínimo dentro do qual seus comentários vivem.

Prática