Comentários em java

Comentários em Java são uma maneira de adicionar notas e explicações ao código, tornando-o mais legível e compreensível para outros desenvolvedores (ou para você mesmo no futuro). Eles são ignorados pelo compilador e não afetam a execução do programa. Existem três tipos principais de comentários em Java:

1. Comentários em java de Linha Única

Comentário de linha única é usado para adicionar uma breve explicação sobre o código na mesma linha ou para descrever uma única linha de código. Começa com // e o comentário se estende até o final da linha.

Exemplo:

int idade = 25; // A variável idade armazena a idade do usuário

2. Comentários em java de Bloco

Comentário de bloco é usado para adicionar explicações mais longas ou para comentar várias linhas de código. Começa com /* e termina com */. Tudo o que estiver entre esses delimitadores é tratado como um comentário.

Exemplo:

/*
Este é um comentário de bloco. Ele pode
ocupar várias linhas e é útil para fornecer
explicações mais detalhadas sobre o código.
*/
int idade = 25;

3. Comentário de Documentação

Comentário de documentação é usado para gerar documentação automática para classes, métodos e campos usando ferramentas como Javadoc. Começa com /** e termina com */. Ele é usado para fornecer descrições que serão usadas para gerar documentação em HTML.

Exemplo:

/**
 * Esta classe representa uma pessoa.
 * Ela contém informações como nome e idade.
 */
public class Pessoa {
    
    /** O nome da pessoa */
    String nome;
    
    /** A idade da pessoa */
    int idade;
    
    /**
     * Constrói uma nova instância de Pessoa com o nome e idade fornecidos.
     * @param nome O nome da pessoa
     * @param idade A idade da pessoa
     */
    public Pessoa(String nome, int idade) {
        this.nome = nome;
        this.idade = idade;
    }
    
    /**
     * Retorna uma string representando a pessoa.
     * @return Uma string com o nome e a idade da pessoa
     */
    @Override
    public String toString() {
        return "Nome: " + nome + ", Idade: " + idade;
    }
}

Boas Práticas para Comentários

• Seja Claro e Conciso: Evite comentários desnecessários. Comentários devem adicionar valor e esclarecer o que o código faz.
• Atualize os Comentários: Mantenha os comentários atualizados com o código. Comentários desatualizados podem levar a mal-entendidos.
• Use Comentários para Explicar “Por Quê”: Em vez de simplesmente descrever o que o código faz (o que o código em si já deve mostrar), use comentários para explicar por que algo é feito de uma certa maneira.
• Evite Comentários Excessivos: Comentários em excesso podem poluir o código. Apenas adicione comentários onde realmente são necessários.

Exemplo Completo com Comentários

/**
 * A classe Exemplo demonstra o uso de comentários em Java.
 */
public class Exemplo {
    
    // O método main é o ponto de entrada do programa
    public static void main(String[] args) {
        
        // Declara uma variável de idade
        int idade = 30; // A variável idade armazena a idade do usuário
        
        /*
         * Abaixo, temos um exemplo de uma estrutura condicional
         * que verifica se a idade é maior de idade.
         */
        if (idade >= 18) {
            System.out.println("Você é maior de idade.");
        } else {
            System.out.println("Você é menor de idade.");
        }
    }
}

Comentários bem escritos ajudam a manter o código mais legível e a facilitar a manutenção e compreensão do mesmo. Se precisar de mais detalhes ou tiver outras dúvidas, estou à disposição!