Java Comentários

Um comentário é um texto dentro do código que o Java ignora completamente. Ele existe só para pessoas: para explicar uma decisão, deixar um lembrete ou "desligar" uma linha sem apagá-la. O Java tem três tipos de comentário, e cada um tem o seu uso.

A ideia: anotações na margem

Quando você estuda num livro, escreve a lápis na margem: "cai na prova", "ver o exemplo da página 30". As anotações ajudam você, mas não mudam o que o livro diz. Os comentários são as anotações do código: o javac pula tudo o que está num comentário, como se não existisse, e o programa funciona exatamente igual com ou sem eles.

Para quem são, então? Para a próxima pessoa que vai ler o código. E, muitas vezes, essa pessoa é você mesmo, daqui a seis meses, sem lembrar por que escreveu aquilo.

1. Comentário de linha: //

Duas barras começam um comentário que vai até o fim da linha. Ele pode ocupar a linha inteira ou ficar depois do código:

// Programa da Loja da Ana: mostra a lista de preços do dia
public class Main {
    public static void main(String[] args) {
        System.out.println("Loja da Ana");      // o título
        System.out.println("Maçã: 3 reais");
        // System.out.println("Promoção: tudo pela metade!");
        System.out.println("Banana: 2 reais");
    }
}

$ java Main.java
Loja da Ana
Maçã: 3 reais
Banana: 2 reais                       « a linha da promoção não aparece: está comentada

// Programa da Loja…

Um comentário na linha inteira, antes da classe. É comum começar o arquivo dizendo o que ele faz.

// o título

Um comentário no fim da linha: o println roda normalmente, e o Java ignora tudo a partir do //.

// System.out.println("Promoção…

Uma instrução inteira dentro de um comentário: para o Java, ela não existe. Dizemos que a linha foi comentada.

Repare que o programa compila igual e a saída tem só três linhas. O // é o comentário mais usado no dia a dia.

// Programa da Loja da Ana: mostra a lista de preços do dia
public class Main {
    public static void main(String[] args) {
        System.out.println("Loja da Ana");      // o título
        System.out.println("Maçã: 3 reais");
        // System.out.println("Promoção: tudo pela metade!");
        System.out.println("Banana: 2 reais");
    }
}

// Programa da Loja da Ana: mostra a lista de preços do dia
public class Main {
    public static void main(String[] args) {
        System.out.println("Loja da Ana");      // o título
        // System.out.println("Maçã: 3 reais");
        System.out.println("Promoção: tudo pela metade!");
        System.out.println("Banana: 2 reais");
    }
}

2. Comentário de bloco: /* … */

Começa com /* e termina com */. Tudo entre os dois é comentário, mesmo que ocupe muitas linhas. É bom para explicações mais longas:

public class Main {
    public static void main(String[] args) {
        /*
           Total do pedido da Ana.
           Os itens custam 10 reais e a entrega, 5.
           Quando a loja tiver frete grátis, tirar o + 5.
        */
        int total = 10 /* itens */ + 5;
        System.out.println(total);
    }
}

$ java Main.java
15

/*

Abre o comentário.

Total do pedido…

Várias linhas de texto livre. O recuo é só para ficar bonito.

*/

Fecha o comentário. Tudo depois disso volta a ser código.

10 /* itens */ + 5

Um comentário de bloco pode até ficar no meio de uma linha de código. O Java lê 10 + 5. Funciona, mas atrapalha a leitura; use pouco.

Muita gente escreve um * no começo de cada linha de dentro, por estética. O Java não exige:

/*
 * Total do pedido da Ana.
 * Os itens custam 10 reais e a entrega, 5.
 */

3. Comentário de documentação: /** … */

Um comentário que começa com dois asteriscos, /**, é especial: é um comentário de documentação, ou Javadoc. Ele fica logo antes de uma classe ou de um método e descreve o que ela faz, para quem vai usar o código:

/**
 * Calcula a média de duas notas.
 *
 * @param a a primeira nota
 * @param b a segunda nota
 * @return a média das duas notas
 */
static double media(double a, double b) {
    return (a + b) / 2;
}

Para o compilador, é um comentário comum: ignorado. Mas a ferramenta javadoc, que vem no JDK, lê esses comentários e gera páginas de documentação, como as da própria biblioteca do Java. As linhas com @ (como @param, "parâmetro", e @return, "devolve") são etiquetas que a ferramenta entende. As IDEs também mostram esse texto quando você passa o mouse sobre o nome do método.

Por enquanto, basta reconhecer o /** quando o vir. Como escrever e gerar a documentação é assunto da aula Javadoc; métodos como o media você vai criar em Métodos.

Os três tipos lado a lado

Comentar código para desligá-lo

Ao procurar um erro ou testar uma ideia, é comum "desligar" linhas sem apagá-las: coloca-se a linha num comentário. Isso se chama comentar o código; tirar o comentário é descomentar.

Quando dá errado

public class Main {
    public static void main(String[] args) {
        /* comentário de fora
           /* comentário de dentro */
        */
        System.out.println("Oi");
    }
}

$ javac Main.java
Main.java:5: error: illegal start of expression
        */
        ^
Main.java:5: error: illegal start of expression
        */
         ^
2 errors

public class Main {
    public static void main(String[] args) {
        /* comentário de fora
           /* comentário de dentro */
        */
        System.out.println("Oi");
    }
}

public class Main {
    public static void main(String[] args) {
        // comentário de fora
        // /* comentário de dentro */
        System.out.println("Oi");
    }
}

public class Main {
    public static void main(String[] args) {
        System.out.println("Site: http://exemplo.com"); // o // dentro das aspas é texto
        System.out.println("Não é /* comentário */");
    }
}

$ java Main.java
Site: http://exemplo.com
Não é /* comentário */

public class Main {
    public static void main(String[] args) {
        /* desligado
        System.out.println("Oi");
    }
}

$ javac Main.java
Main.java:3: error: unclosed comment
        /* desligado
        ^
Main.java:7: error: reached end of file while parsing
2 errors

Bons e maus comentários

Comentar muito não é comentar bem. O código já diz o que está sendo feito; o bom comentário diz por que.

Bons comentários costumam:

• explicar uma regra de negócio: // lojas com mais de 3 anos não pagam a taxa;
• avisar sobre algo não óbvio: // a divisão é inteira de propósito: queremos caixas completas;
• marcar o que falta fazer: // TODO: aceitar pagamento em cartão (muitos editores listam todos os TODO, "a fazer");
• documentar classes e métodos com /** */ para quem vai usá-los.

Neste guia, os exemplos usam poucos comentários, porque cada linha já é explicada no texto da aula. Nos seus programas, comente o que você precisaria lembrar daqui a seis meses.

public class Main {
    public static void main(String[] args) {
        int itens = 10;
        int entrega = 5;
        System.out.println("Total: " + (itens + entrega));
    }
}

public class Main {
    public static void main(String[] args) {
        int itens = 10;
        int entrega = 5; // taxa de entrega fixa
        System.out.println("Total: " + (itens + entrega));
    }
}

Exercícios

Resumo

• Comentários são ignorados pelo compilador; servem a quem lê o código.
• // comenta até o fim da linha; /* … */ comenta um bloco, de qualquer tamanho.
• /** … */ é o comentário de documentação, lido pelo javadoc (veja Javadoc).
• Comentar uma linha "desliga" o código sem apagar; prefira // (ou Ctrl+/).
• /* */ não se aninha: o primeiro */ fecha tudo.
• // e /* dentro de aspas são texto comum.
• Bom comentário explica o porquê, não repete o código, e é atualizado junto com ele.