C++ Comentários

Um comentário é um texto dentro do código que o compilador ignora por completo. Ele existe para pessoas: para explicar por que o código foi escrito daquele jeito, deixar um lembrete, ou "desligar" uma linha sem apagá-la. O C++ tem dois tipos de comentário, // e /* */, e cada um tem uma armadilha que você vai conhecer nesta aula.

Você vai aprender

O comentário de linha, //.
O comentário de bloco, /* … */, que pode ocupar várias linhas.
Como "comentar" código para testar o programa sem uma parte dele.
Por que "// isto" dentro de aspas não é comentário.
O que escrever (e o que não escrever) num comentário.
Os erros reais: comentário que não fecha, /* dentro de /*, a barra invertida no fim de um //.
O que são os comentários /** */ do Doxygen.

Os programas foram compilados na máquina da Ana com g++ -std=c++23 -Wall -Wextra (g++ 15.2) e, quando indicado, com o clang++ 21.1, o compilador do editor do guia.

A ideia: anotações a lápis na receita

A Ana tem um caderno de receitas cheio de anotações a lápis na margem: "a vovó usava menos açúcar", "forno da casa nova esquenta mais, tirar 5 minutos antes". Quem faz o bolo segue a receita; as anotações ajudam quem lê. E quando ela quer testar o bolo sem a cobertura, não arranca a página: risca a parte da cobertura, que continua legível ali, para voltar depois.

Em C++, as anotações e os riscos são os comentários. O compilador "pula" tudo o que estiver dentro de um comentário, como se não existisse.

1. Comentário de linha: `//`

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

// Programa da lista de compras da Ana
#include <iostream>

int main() {
    std::cout << "Arroz\n";   // o mais importante
    std::cout << "Leite\n";   // o desnatado acabou
}

$ g++ -std=c++23 -Wall -Wextra compras.cpp -o compras && ./compras
Arroz
Leite

std::cout << "Arroz\n";: Código normal: o compilador lê e executa.
//: A partir daqui, até o fim da linha, é comentário.
o mais importante: O texto do comentário. Pode ter qualquer coisa, inclusive acentos, símbolos e código. Não aparece na saída.

O // é o comentário mais usado em C++. Na linha seguinte, o código volta ao normal, sem precisar "fechar" nada.

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

Barra e asterisco, /*, começam um comentário que vai até o asterisco e barra, */, onde quer que estejam. Ele pode ocupar várias linhas:

/*
   Lista de compras da Ana
   Escrito em outubro, para a aula de comentários.
   Mostra só o que falta comprar.
*/
#include <iostream>

int main() {
    std::cout << "Arroz\n";
}

Ou só um pedacinho, no meio de uma linha de código (o compilador trata o comentário como um espaço):

#include <iostream>

int main() {
    std::cout << "Total: " << /* preço */ 25 << "\n";
}

$ g++ -std=c++23 -Wall -Wextra meio.cpp -o meio && ./meio
Total: 25

Comentários no meio da linha são raros; em geral eles atrapalham a leitura. O uso típico do /* */ é um texto de várias linhas, como o cabeçalho acima.

Asteriscos decorativos

Você vai ver comentários de bloco com um * no começo de cada linha:

/*
 * Lista de compras da Ana
 * Mostra só o que falta comprar.
 */

Os * do meio são só enfeite: para o compilador, tudo entre /* e */ é comentário. Muitos editores acrescentam esses asteriscos sozinhos quando você aperta Enter dentro de um comentário.

3. Comentar código para testar

O segundo grande uso dos comentários é desligar código temporariamente. Quer ver como o programa se comporta sem uma linha? Em vez de apagá-la (e ter de digitar de novo depois), ponha // na frente:

#include <iostream>

int main() {
    std::cout << "Arroz\n";
    // std::cout << "Feijão\n";
    std::cout << "Café\n";
}

$ g++ -std=c++23 -Wall -Wextra lista.cpp -o lista && ./lista
Arroz
Café                     « o Feijão não aparece: a linha virou comentário

Para desligar várias linhas de uma vez, envolva-as em /* */. E repare que um texto entre aspas com // dentro não é comentário: dentro das aspas, // é só texto.

// Programa da lista de compras da Ana
#include <iostream>

int main() {
    std::cout << "Arroz\n";   // o mais importante
    /* std::cout << "Feijão\n";
       std::cout << "Café\n"; */
    std::cout << "Leite\n";
    std::cout << "// isto não é comentário\n";
}

$ g++ -std=c++23 -Wall -Wextra coment.cpp -o coment && ./coment
Arroz
Leite
// isto não é comentário

Linha	O que acontece
1	Comentário de linha inteira: ignorado.
5	Mostra `Arroz`; o `// o mais importante` é ignorado.
6 e 7	Tudo entre `/` e `/` é ignorado, inclusive o código: Feijão e Café somem.
8	Mostra `Leite`.
9	As `//` estão dentro das aspas: fazem parte do texto e aparecem na tela.

O atalho do editor

Quase todo editor de código comenta e descomenta as linhas selecionadas com um atalho: Ctrl + / na maioria deles (em alguns teclados brasileiros, o VS Code usa Ctrl + ;). Ele põe ou tira // no começo de cada linha. Veja os atalhos do seu em Editores e IDEs.

Missão: sem apagar nenhuma linha, transforme em comentário a linha da chuva, para a saída ficar só com Bom dia! e Vamos à feira.. Depois, acrescente um comentário seu no fim da última linha e rode de novo: a saída não deve mudar.

#include <iostream>

int main() {
    std::cout << "Bom dia!\n";
    std::cout << "Hoje chove.\n";
    std::cout << "Vamos à feira.\n";
}

#include <iostream>

int main() {
    std::cout << "Bom dia!\n";
    // std::cout << "Hoje chove.\n";
    std::cout << "Vamos à feira.\n";   // sábado de manhã
}

Não deixe código comentado para sempre

Comentar código é ótimo para testar. Mas, depois de decidir, apague o que não vai voltar. Um arquivo cheio de linhas desligadas confunde quem lê ("isto ainda vale? por que está aqui?"). Para guardar versões antigas do código existe o Git, que guarda todo o histórico do projeto.

4. O que escrever num comentário

Um bom comentário diz por que, e não o que. O "o que" o próprio código já diz. Compare:

Comentário inútil (repete o código)	Comentário útil (explica o motivo)
`std::cout << "\n"; // mostra uma quebra de linha`	`std::cout << "\n"; // separa o cabeçalho da lista`
`// soma 5`	`// a loja cobra 5 reais de entrega`
`// main`	`// Programa da lista de compras: mostra o que falta comprar`

Outras dicas:

Um comentário no topo do arquivo, dizendo o que o programa faz, ajuda muito quem abre o arquivo pela primeira vez (inclusive você daqui a seis meses).
Comentário errado é pior que nenhum. Mudou o código? Atualize o comentário.
Acentos são permitidos nos comentários, porque o compilador nem os lê. Em projetos com pessoas de vários países, os comentários costumam ser em inglês; neste guia, são em português.
Muitos programadores marcam pendências com // TODO: ("a fazer"), e os editores destacam essas linhas.

5. `/** */`: comentários de documentação (Doxygen)

Você vai encontrar comentários que começam com dois asteriscos, /**, ou com três barras, ///. Para o compilador, eles são comentários comuns (/** é um /* seguido de um *). Mas uma ferramenta chamada Doxygen lê esses comentários especiais e gera um site com a documentação do projeto. As palavras com @, como @param ("parâmetro"), são marcações para ela:

#include <iostream>

/**
 * Mostra o total da compra na tela.
 *
 * @param total valor da compra, em reais
 */
void mostrarTotal(int total) {
    std::cout << "Total: R$ " << total << "\n";
}

int main() {
    mostrarTotal(25); // a Ana gastou 25 reais
}

$ g++ -std=c++23 -Wall -Wextra doxy.cpp -o doxy && ./doxy
Total: R$ 25

Não se preocupe com a função mostrarTotal: funções são do Nível 2 (Funções). Por enquanto, basta reconhecer o /** */ quando aparecer. Os editores também usam esses comentários: ao passar o mouse sobre mostrarTotal, o VS Code mostra o texto do comentário.

Quando dá errado

error: unterminated comment: o comentário que não fecha

#include <iostream>

int main() {
    /* comentário que esqueci de fechar
    std::cout << "Olá!\n";
}

$ g++ -std=c++23 -Wall -Wextra aberto.cpp -o aberto
aberto.cpp:4:5: error: unterminated comment
    4 |     /* comentário que esqueci de fechar
      |     ^
aberto.cpp: In function ‘int main()’:
aberto.cpp:3:13: error: expected ‘}’ at end of input
    3 | int main() {
      |            ~^

O que significa: "comentário não terminado". O /* da linha 4 nunca encontrou um */, então todo o resto do arquivo virou comentário, inclusive o std::cout e a } final. Por isso vem o segundo erro: "esperava } no fim da entrada", porque a main ficou sem fechar. O Clang diz o mesmo:

$ clang++ -std=c++23 -Wall -Wextra aberto.cpp -o aberto
aberto.cpp:4:5: error: unterminated /* comment
    4 |     /* comentário que esqueci de fechar
      |     ^
aberto.cpp:6:2: error: expected '}'
    6 | }
      |  ^
aberto.cpp:3:12: note: to match this '{'
    3 | int main() {
      |            ^
2 errors generated.

Como consertar: feche o comentário com */ onde ele deve acabar. Uma pista visual: no editor, o código depois de um /* aberto fica todo na cor dos comentários (geralmente cinza ou verde).

‘/*’ within comment: um /* */ dentro do outro

A Ana quis desligar um trecho com /* */, mas dentro dele já havia um comentário de bloco:

#include <iostream>

int main() {
    /* desligando um trecho:
    std::cout << "Um\n";   /* explicação antiga */
    std::cout << "Dois\n";
    */
    std::cout << "Três\n";
}

$ g++ -std=c++23 -Wall -Wextra aninhado.cpp -o aninhado
aninhado.cpp:5:28: warning: ‘/*’ within comment [-Wcomment]
    5 |     std::cout << "Um\n";   /* explicação antiga */
aninhado.cpp: In function ‘int main()’:
aninhado.cpp:7:6: error: expected primary-expression before ‘/’ token
    7 |     */
      |      ^

O que significa: comentários de bloco não se aninham (um não pode ficar dentro do outro). O comentário da linha 4 termina no primeiro */ que aparecer, que é o da linha 5. Então a linha 6 volta a ser código (o "Dois" seria mostrado), e o */ da linha 7 fica sobrando, solto no meio do código: "esperava uma expressão antes de /". O aviso da linha 5 ("/* dentro de comentário") é a pista da causa.

Como consertar: use // em cada linha (o atalho do editor faz isso), ou o truque do #if 0, logo abaixo.

multi-line comment: a barra invertida que engole a próxima linha

#include <iostream>

int main() {
    // pasta do Windows: C:\fotos\
    std::cout << "Esta linha some!\n";
    std::cout << "Esta aparece.\n";
}

$ g++ -std=c++23 pasta.cpp -o pasta && ./pasta
Esta aparece.            « sem -Wall: nenhum aviso, e uma linha sumiu
$ g++ -std=c++23 -Wall -Wextra pasta.cpp -o pasta && ./pasta
pasta.cpp:4:5: warning: multi-line comment [-Wcomment]
    4 |     // pasta do Windows: C:\fotos\
      |     ^
Esta aparece.

O que significa: em C++, uma barra invertida \ no último caractere de uma linha junta essa linha com a seguinte. O comentário // "continuou" na linha 5, e o primeiro std::cout virou comentário, sem nenhum erro. Só o -Wall avisa: "comentário de várias linhas". (O Clang avisa com multi-line // comment.) É mais um motivo para compilar sempre com -Wall.

Como consertar: não termine um // com \. Escreva C:\fotos sem a barra final, ou ponha algo depois dela.

O truque do `#if 0`

Para desligar um trecho grande que já tem comentários /* */ dentro, programadores C++ usam uma ordem do pré-processador: tudo entre #if 0 e #endif é descartado antes da compilação, com ou sem comentários dentro.

#include <iostream>

int main() {
#if 0
    std::cout << "Um\n";   /* explicação antiga */
    std::cout << "Dois\n";
#endif
    std::cout << "Três\n";
}

$ g++ -std=c++23 -Wall -Wextra if0.cpp -o if0 && ./if0
Três

O 0 quer dizer "falso": "se falso, inclua este trecho", ou seja, nunca. Trocando por #if 1, o trecho volta. O #if é explicado em O Pré-processador.

Referência rápida

Escrita	O que faz	Cuidado
`// texto`	Comentário até o fim da linha	Não termine com `\`
`/* texto */`	Comentário até o `*/`, em uma ou várias linhas	Não pode ficar dentro de outro `/* */`; precisa fechar
`// codigo();`	Desliga uma linha de código para testar	Apague depois de decidir
`"// texto"`	Não é comentário: é texto e aparece na tela
`/** … */`, `///`	Comentário de documentação (lido pelo Doxygen)	Para o compilador, é comentário comum
`#if 0` … `#endif`	Desliga um trecho, mesmo com `/* */` dentro

Exercícios

1. Comentário de linha

Complete para que o texto depois do código seja um comentário:

std::cout << "Arroz\n"; comprar 5 kg

2. Fechar o bloco

Complete o símbolo que fecha um comentário de bloco:

/* lista da semana

3. O que este programa mostra? std::cout << "A\n"; // std::cout << "B\n"; e, na linha de baixo, std::cout << "// C\n";

A, B e C Só A A e // C Nada: dá erro

4. A Ana abriu um /* na linha 3 e esqueceu o */. O que acontece?

Só a linha 3 vira comentário Todo o resto do arquivo vira comentário e o compilador dá unterminated comment O compilador fecha o comentário sozinho no fim da linha Nada: o compilador ignora o /*

5. Qual comentário é mais útil?

std::cout << "\n"; // mostra \n // aqui tem um cout // código // a nota fiscal precisa de uma linha em branco antes do total

Missão final: a receita comentada

Missão: o bolo de hoje vai sem chocolate e sem cobertura. Sem apagar nenhuma linha de código: (1) desligue as duas últimas linhas de std::cout com um único comentário /* */; (2) acrescente no topo do arquivo um comentário // explicando o que o programa faz. A saída deve ser:

Receita de bolo
Farinha
Ovos
Açúcar

#include <iostream>

int main() {
    std::cout << "Receita de bolo\n";
    std::cout << "Farinha\n";
    std::cout << "Ovos\n";
    std::cout << "Açúcar\n";
    std::cout << "Chocolate\n";
    std::cout << "Cobertura\n";
}

// Mostra os ingredientes do bolo da Ana
#include <iostream>

int main() {
    std::cout << "Receita de bolo\n";
    std::cout << "Farinha\n";
    std::cout << "Ovos\n";
    std::cout << "Açúcar\n";
    /* std::cout << "Chocolate\n";
    std::cout << "Cobertura\n"; */
}

Resumo

Comentários são para pessoas; o compilador os ignora.
// comenta até o fim da linha. /* */ comenta tudo entre a abertura e o primeiro fechamento, em uma ou várias linhas.
Comentar código serve para testar sem apagar. Depois de decidir, apague o que sobrou.
Dentro de aspas, // e /* são texto comum.
Comente o porquê, não o o quê.
Armadilhas: /* sem */ (unterminated comment), /* */ dentro de /* */, e \ no fim de um // (só o -Wall avisa). Para desligar trechos grandes, use #if 0 … #endif.
/** */ e /// são comentários de documentação, lidos pelo Doxygen.