Comentários sobre Java

Em Java, os comentários são instruções não executáveis que fornecem explicações ou anotações no código. Eles são usados para melhorar a legibilidade do código e ajudar os desenvolvedores a entender a finalidade e a funcionalidade do código. Os comentários são ignorados pelo compilador Java durante a execução.

Tipos de comentários

O Java oferece suporte a três tipos de comentários:

1. Comentários de uma linha
2. Comentários com várias linhas
3. Documentação Comentários

Comentários de uma linha

Os comentários de linha única começam com // e continuam até o final da linha. Elas são usadas para explicações breves ou anotações no código.

Sintaxe

 // This is a single-line comment
int number = 10; // This initializes the variable

Comentários com várias linhas

Os comentários de várias linhas, também conhecidos como comentários em bloco, começam com /* e terminam com */. Eles são úteis para comentar várias linhas de código ou fornecer explicações detalhadas.

Sintaxe

 /*
This is a multi-line comment.
It can span multiple lines.
*/
int number = 20;

Documentação Comentários

Os comentários de documentação, ou comentários Javadoc, são comentários especiais usados para gerar documentação de API. Eles começam com /** e terminam com */. Esses comentários são normalmente colocados antes das declarações de classe, método ou campo para descrever sua finalidade e uso.

Sintaxe

 /**
 * This is a documentation comment.
 * @param args Command line arguments
 */
public static void main(String[] args) {
    // Code goes here
}

Exemplos

Exemplo 1: Uso de comentários de linha única

 public class SingleLineCommentExample {
    public static void main(String[] args) {
        // Print a message to the console
        System.out.println("Hello, World!"); // Output message
    }
}

Exemplo 2: Uso de comentários de várias linhas

 public class MultiLineCommentExample {
    public static void main(String[] args) {
        /*
         * This block of code prints a message
         * to the console.
         */
        System.out.println("Hello, Java!");
    }
}

Exemplo 3: Uso de comentários de documentação

 /**
 * The Calculator class provides basic arithmetic operations.
 */
public class Calculator {
    /**
     * Adds two integers.
     * @param a First integer
     * @param b Second integer
     * @return Sum of a and b
     */
    public int add(int a, int b) {
        return a + b;
    }
}

Tags Javadoc

Os comentários Javadoc podem incluir tags específicas para fornecer informações adicionais sobre os elementos de código que descrevem. As tags comumente usadas incluem:

• @param: Descreve um parâmetro de método.
• @return: Descreve o valor de retorno de um método.
• @throws ou @exception: Documenta uma exceção lançada por um método.

Dicas e práticas recomendadas

• Clareza: Use comentários para esclarecer a lógica complexa do código, mas evite dizer o óbvio.
• Consistência: Manter um estilo consistente para os comentários em toda a base de código.
• Atualizar comentários: Certifique-se de que os comentários sejam atualizados quando o código for alterado para evitar discrepâncias.
• Evite o excesso de comentários: Não use comentários em excesso; o código deve ser autoexplicativo sempre que possível.
• Javadoc: Use comentários Javadoc para APIs públicas para facilitar a geração automática de documentação.