Comentários

Introdução

Em Java, comentários são utilizados para documentar o código, explicar regras de negócio, facilitar a manutenção e não interferem na execução do programa.

Tipos de Comentários em Java

Em Java, existem três tipos de comentários, cada um com uma finalidade específica.

Comentário de linha única

Utilizado para explicações rápidas ou observações pontuais.

int idade = 18; // idade mínima para cadastro

Tudo que estiver após // na mesma linha será ignorado.

Comentário de múltiplas linhas

Utilizado quando a explicação é maior ou ocupa mais de uma linha.

/*
 Este bloco calcula o valor total do pedido
 considerando impostos e descontos aplicáveis
 */
BigDecimal total = calcularTotal();

Pode ser usado também para comentar temporariamente trechos de código.

Comentário de documentação (JavaDoc)

Utilizado para documentar classes, métodos e atributos, permitindo a geração automática de documentação.

/**
 * Calcula o valor de cada parcela de um pagamento.
 *
 * @param valorTotal valor total da compra
 * @param quantidadeParcelas número de parcelas
 * @return valor de cada parcela
 */
public static BigDecimal calcularValorParcela(BigDecimal valorTotal,
                                               int quantidadeParcelas) {
    return valorTotal.divide(
            BigDecimal.valueOf(quantidadeParcelas),
            2,
            RoundingMode.HALF_EVEN
    );
}

Boas práticas ao usar comentários

• Use comentários para explicar o porquê, não o óbvio;
• Prefira nomes de variáveis e métodos claros ao invés de excesso de comentários;
• Mantenha comentários atualizados com o código;
• Utilize JavaDoc para métodos públicos e APIs;
• Evite comentários redundantes.

Exemplo de comentário desnecessário (❌)

int total = 10; // atribui 10 à variável total

Exemplo de comentário útil (✅)

int total = 10; // valor mínimo exigido pela regra de negócio

Observação importante

Resumo:

Os comentários são trechos de texto ignorados pelo compilador e servem para documentar, explicar ou desativar temporariamente partes do código. Em Java, existem três tipos principais de comentários.

1. Comentário de Linha

Utiliza // para comentar uma única linha.

// Este é um comentário de linha
System.out.println("Olá, Mundo!");

2. Comentário de Múltiplas Linhas

Utiliza /* */ para comentar uma ou mais linhas.

/*
   Este é um comentário
   de múltiplas linhas.
*/
System.out.println("Java");

3. Comentário de Documentação (Javadoc)

Utiliza /** */ e é usado para gerar documentação automática do código por meio da ferramenta Javadoc.

/**
 * Exibe uma mensagem de boas-vindas.
 * @author João
 * @version 1.0
 */
public void exibirMensagem() {
    System.out.println("Bem-vindo!");
}

Tabela Resumo

Boas Práticas

• Utilize comentários para explicar a intenção do código, não o óbvio.
• Mantenha os comentários atualizados conforme o código evolui.
• Prefira nomes de variáveis e métodos claros para reduzir a necessidade de comentários excessivos.
• Use Javadoc em classes, métodos e interfaces públicas para facilitar a manutenção e documentação do projeto.