comentários

O que são comentários?

Comentários são textos explicativos adicionados no código-fonte para ajudar programadores a entender a lógica do programa. Eles não fazem parte do código executável, e o compilador ignora todo o conteúdo dos comentários durante a compilação.

Também usamos comentários para depurar e localizar falhas. Quando um erro surge e não sabemos onde ele está, podemos comentar trechos suspeitos de código; esses trechos são ignorados pelo compilador, permitindo isolar o problema passo a passo.

Comentários são semelhantes às anotações que fazíamos nos livros escolares: esses textos extras facilitam o entendimento do conteúdo principal.

Tipos de comentários

Tipo de comentário	Marca de abertura	Marca de fechamento	Regras principais
Comentário de linha única Single-line	//	Fim da linha atual	Vale apenas para a linha inteira; tudo após // na mesma linha é descartado
Comentário de bloco Delimited	/*	*/	Cobre várias linhas ou trechos dentro de uma linha; não aceita aninhamento
Comentário de documentação Documentation	///	Fim da linha atual	Suporta tags XML embutidas, usado para gerar documentação de API do projeto automaticamente

1. Comentários de linha única //

1. Tudo que vem após // até o fim da linha atual é ignorado pelo compilador;
2. Pode ser escrito no início da linha ou depois do código funcional;
3. Não tem restrição de aninhamento e não causa conflito de sintaxe com os blocos /* */.

// Comentário no início da linha: declarar variável numérica
int num = 10; // Comentário após código: armazena o valor 10
// int temp = 99; // Linha toda comentada para depuração; desativa código temporariamente sem excluí-lo, fácil de restaurar depoisCode language: JavaScript (javascript)

2. Comentários de bloco /* */

1. Precisa de marca de abertura e fechamento pareados; todo conteúdo entre /* e */ é ignorado;
2. Suporta várias linhas seguidas e também trechos parciais dentro de uma linha;
3. É proibido aninhar blocos de comentário. O compilador encerra o comentário no primeiro */ encontrado, e qualquer */ solto restante gera erro de sintaxe.

Exemplo básico

/*
Exemplo de bloco de comentário com múltiplas linhas
O compilador ignora todo conteúdo interno
Você pode escrever texto em quantas linhas quiser
*/
string str = "Teste";Code language: JavaScript (javascript)

/*
Multi-line delimited comment example
All content here is ignored by the compiler
Text can span any number of lines
wellcome to foxdevelop.com
*/
string greet = "wellcome to foxdevelop.com";
Console.WriteLine(greet);Code language: JavaScript (javascript)

Aninhamento causa erro de compilação

Ao colocar um bloco dentro de outro, o último marcador de fechamento fica sem marca de abertura correspondente, causando falha na compilação.

Comentário parcial dentro da linha

Oculta apenas um trecho do código; na exemplo abaixo a variável a fica totalmente comentada.

int /*a,*/ b; 
// Equivale a int b; o trecho "a," entre as marcas é excluído da execuçãoCode language: JavaScript (javascript)

Exemplo incorreto de bloco aninhado

Retorna erro de sintaxe

/* Início do comentário externo
    /* Comentário interno aninhado (lido apenas como texto comum, sem efeito) */
// O primeiro */ acima fecha o bloco externo, o último */ não tem abertura correspondente e quebra a sintaxe
*/Code language: JavaScript (javascript)

O símbolo /* dentro de // não abre bloco de comentário

Os marcadores de bloco são tratados como texto normal dentro do comentário de linha única e não funcionam como tal.

// Este é um comentário de linha única /* o /* aqui é só texto, não inicializa bloco
int x = 5;
/* Abre o bloco de comentário */ // O bloco termina aqui, o // posterior funciona normalmenteCode language: JavaScript (javascript)

3. Comentários de documentação ///

1. Parece com o comentário de linha única, marcado com três barras consecutivas ///;
2. Aceita tags XML embutidas; IDEs e ferramentas leem essas marcações para gerar documentação de referência de API;
3. Geralmente escrito acima de classes, métodos e propriedades para documentar interfaces públicas.

/// <summary>
/// Classe principal, ponto de entrada do aplicativo
/// </summary>
class Program
{
    /// <summary>
    /// Método de entrada do programa
    /// </summary>
    /// <param name="args">Vetor com argumentos da linha de comando</param>
    static void Main(string[] args)
    {

    }
}Code language: JavaScript (javascript)

Resumo

1. Blocos de comentário /* */ não aceitam aninhamento; a leitura do comentário para no primeiro */ encontrado;
2. Comentários de linha única // valem só para a linha atual, não ultrapassam linhas; qualquer /* dentro é lido como caractere comum;
3. A sintaxe e comportamento dos comentários de linha e bloco no C# são idênticos ao C/C++;
4. Regra para escrever comentários: não repita o que o código faz literalmente, foque em explicar o objetivo de negócio e a lógica de projeto para facilitar manutenção futura. Comentários que só repetem nomes de variáveis não têm utilidade.
5. Explicação curta em linha, desativar temporariamente uma linha de código → use //
6. Desativar várias linhas de uma vez, ocultar trecho parcial dentro de linha → use /* */
7. Documentar interfaces de classe/método, gerar documentação automática do projeto → use ///

* Como gerar documentação

A seção abaixo é apenas referência. Comentários de documentação são usados principalmente em projetos grandes; durante o aprendizado basta saber que essa funcionalidade existe.

Configuração no Visual Studio

1. Clique com o botão direito no projeto → Propriedades → aba Build (Compilar);
2. Marque a opção: Generate XML documentation file (Gerar arquivo de documentação XML);
3. Caminho padrão de saída: bin\Debug\NomeDoProjeto.xml, é possível definir um caminho personalizado;
4. Marque para All Configurations (Todas as configurações) para funcionar em Debug e Release;
5. Recompile o projeto; um arquivo XML completo com todos os comentários será criado na pasta destino.

Configuração via .NET CLI (sem Visual Studio)

Edite o arquivo .csproj do projeto e adicione o trecho abaixo:

<PropertyGroup>
  <GenerateDocumentationFile>true</GenerateDocumentationFile>
</PropertyGroup>Code language: HTML, XML (xml)

Execute o comando de build:

dotnet build

Funcionalidade

Esse arquivo XML guarda todo conteúdo das tags <summary>、<param>、<returns> e serve como fonte de dados para gerar documentação oficial. O Visual Studio também lê esse arquivo para exibir os comentários nos tooltips flutuantes do IntelliSense.

Outras ferramentas de documentação

DocFX da Microsoft (recomendado oficialmente, cria sites de documentação HTML estáticos)

Sandcastle (ferramenta clássica da Microsoft para gerar arquivos de ajuda offline CHM)

Ferramentas leves de terceiros (ex: Doxygen)

Explicação completa dos três tipos de sintaxe de comentários