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