Comentários em C++: uma linha // e múltiplas linhas /* */

Para que servem os comentários

Um comentário é um texto no seu código-fonte que o compilador C++ ignora por completo. Ele nunca chega ao programa compilado: existe apenas para as pessoas que leem o código. Você usa comentários para explicar por que algo é feito de certa forma, para deixar lembretes ou para desativar código temporariamente sem apagá-lo.

Partindo da sintaxe de C++ que você já conhece, os comentários são uma das poucas coisas que você pode colocar em quase qualquer lugar e o compilador simplesmente vai ignorá-los. C++ tem dois tipos: de uma linha (//) e de bloco em múltiplas linhas (/* */).

Comentários de uma linha

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

#include <iostream>
using namespace std;

int main() {
    // Exibe uma saudação no console
    cout << "Hello, C++!" << endl;

    int score = 90; // um comentário também pode vir depois do código
    cout << score << endl;
    return 0;
}

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

Comentários de bloco em múltiplas linhas

Quando sua nota ocupa várias linhas, um comentário de bloco fica mais limpo do que prefixar cada linha com //. Um comentário de bloco começa com /* e termina com */. Tudo entre os dois - por quantas linhas forem - é ignorado.

#include <iostream>
using namespace std;

int main() {
    /*
     * 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.
     */
    cout << "Block comments are handy." << endl;
    return 0;
}

Os caracteres * alinhados ao longo da borda 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. Um comentário de bloco pode até ficar no meio de uma linha - int x = 5 /* width */ + 2; é válido -, embora isso rapidamente fique difícil de ler.

Comentando 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 desligar várias linhas de uma vez.

#include <iostream>
using namespace std;

int main() {
    cout << "This line runs." << endl;

    // cout << "This line is disabled." << endl;

    /*
    cout << "So is this one," << endl;
    cout << "and this one too." << endl;
    */

    cout << "This line runs as well." << endl;
    return 0;
}

Execute-o e você verá que apenas as duas linhas "runs" são impressas. As instruções cout comentadas são invisíveis para o compilador.

O detalhe da não aninhação

Uma armadilha que pega os iniciantes: comentários de bloco não aninham. O primeiro */ fecha o comentário, não importa quantos /* vieram antes. Então você não pode envolver um bloco /* ... */ dentro de outro bloco /* ... */ - o */ interno encerra tudo, e o que vem depois vira código de novo (geralmente um erro de sintaxe).

/*  Trying to disable a region that already has a block comment...
    int n = 10; /* the width */
    cout << n;
*/  // the first */ above already closed the comment - this line is now stray code

O comentário externo termina no */ depois de the width, então o restante deixa de estar comentado e o compilador trava no */ final. Quando você precisar desativar uma região que já contém comentários de bloco, use // em cada linha. A maioria dos editores alterna comentários de linha em toda uma seleção com um único atalho de teclado, o que contorna o problema por completo.

Bons comentários vs. ruído

Um comentário deve explicar algo que o código não consegue dizer por conta própria. Comentários que apenas repetem o código adicionam bagunça e tendem a ficar desatualizados conforme o código muda.

// Bad: just repeats what the code obviously does
i = i + 1; // add one to i

// Better: explains the reason, which the code can't show
retries++; // back off and retry; the API is rate-limited at 5 req/sec

Procure tornar o código legível por meio de nomes claros e boa estrutura, e reserve os comentários para o porquê: intenção, escolhas de projeto, casos extremos e links para o contexto. Se você se pegar escrevendo um comentário para explicar uma linha confusa, isso costuma ser um sinal para renomear uma variável ou dividir a lógica em uma função com um bom nome.

Próximo: Variáveis

Agora que você consegue 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 embutidos que elas guardam e as regras que C++ impõe por ser de tipagem estática.