Comentários em Java: de uma linha, de várias linhas e Javadoc

Para que servem os comentários

Um comentário é um texto no seu código-fonte que o compilador Java ignora por completo. Ele nunca faz parte do programa em execução: existe apenas para as pessoas que leem o código. Você usa comentários para explicar por que algo é feito de determinada maneira, para deixar lembretes ou para desativar código temporariamente sem apagá-lo.

Java tem três tipos de comentários: de uma linha (//), de bloco de várias linhas (/* */) e comentários de documentação Javadoc (/** */). Todos cumprem a mesma função básica — serem ignorados em tempo de compilação —, mas você recorre a cada um em situações diferentes.

Comentários de uma linha

Duas barras (//) iniciam um comentário que se estende até o final da linha atual. O compilador ignora tudo desde o // até a quebra de linha.

public class Main {
    public static void main(String[] args) {
        // Imprime uma saudação no console
        System.out.println("Hello, Java!");

        int score = 90; // um comentário também pode ficar depois do código
        System.out.println(score);
    }
}

Repare que o segundo comentário divide a linha com código real. Tudo o que vem antes do // ainda é executado; apenas a parte depois dele é ignorada. Esse é o estilo de comentário mais comum para notas curtas.

Comentários de bloco de várias linhas

Quando sua nota abrange várias linhas, um comentário de bloco é mais limpo do que prefixar cada linha com //. Um comentário de bloco começa com /* e termina com */. Tudo o que houver entre os dois — não importa quantas linhas — é ignorado.

public class Main {
    public static void main(String[] args) {
        /*
         * Este programa mostra um comentário de bloco.
         * Os asteriscos no início de cada linha são apenas uma
         * convenção de legibilidade: eles não são obrigatórios.
         */
        System.out.println("Block comments are handy.");
    }
}

Os caracteres * alinhados à esquerda são uma convenção de estilo, não uma regra. As únicas partes que realmente importam são o /* de abertura e o */ de fechamento.

Comentar código

Os comentários são a forma padrão de desativar código enquanto você experimenta, sem apagá-lo. Use // para uma única linha, ou um comentário de bloco para desativar várias linhas de uma vez.

public class Main {
    public static void main(String[] args) {
        System.out.println("This line runs.");

        // System.out.println("This line is disabled.");

        /*
        System.out.println("So is this one,");
        System.out.println("and this one too.");
        */

        System.out.println("This line runs as well.");
    }
}

Execute e você verá que apenas as duas linhas "runs" são impressas. As chamadas a println comentadas são invisíveis para o compilador.

Uma pegadinha comum: comentários de bloco não podem ser aninhados. O primeiro */ fecha o comentário, não importa quantos /* venham antes. Por isso você não pode envolver um bloco /* ... */ dentro de outro bloco /* ... */: o */ interno encerra tudo e o restante vira um erro de sintaxe. Se você precisar desativar uma região que já contém comentários de bloco, use // em cada linha (a maioria dos editores faz isso com um único atalho de teclado).

Comentários de documentação Javadoc

Um comentário Javadoc parece um comentário de bloco, mas começa com /** — dois asteriscos. Ele serve para documentar uma classe, método ou campo, e fica logo acima daquilo que descreve. A ferramenta javadoc os transforma em documentação HTML navegável da API, e as IDEs os exibem como dicas ao passar o cursor.

public class Main {
    /**
     * Returns the larger of two integers.
     *
     * @param a the first number
     * @param b the second number
     * @return whichever of {@code a} and {@code b} is greater
     */
    static int max(int a, int b) {
        return a > b ? a : b;
    }

    public static void main(String[] args) {
        System.out.println(max(3, 9));
    }
}

As tags @param, @return e @throws são campos estruturados que a ferramenta entende. Para o compilador isso continua sendo apenas um comentário ignorado: o valor está inteiramente na documentação que ele produz e nas dicas que a IDE oferece a outros desenvolvedores (e a você mesmo, seis meses depois).

Bons comentários x ruído

Um comentário deve explicar algo que o código não consegue dizer por si só. Comentários que apenas repetem o que o código faz acrescentam bagunça e tendem a ficar desatualizados conforme o código muda.

// Ruim: apenas repete o que o código faz de forma óbvia
int i = i + 1; // soma um a i

// Melhor: explica o motivo, que o código não consegue mostrar
retries++; // recua e tenta de novo; a API tem limite de 5 req/seg

Procure deixar o código legível por meio de nomes claros e uma boa estrutura, e reserve os comentários para o porquê: intenção, compromissos, casos extremos e links de contexto. Se você se pegar escrevendo um comentário para explicar uma linha confusa, isso costuma ser um sinal de que é melhor renomear uma variável ou extrair um método.

Próximo: Variáveis

Agora que você sabe anotar seu código, o próximo bloco de construção é armazenar dados nele. A próxima página aborda as variáveis: como declará-las, os tipos que elas armazenam e as regras que o Java impõe por ser de tipagem estática.