Comentários

Ao escrever código, você rapidamente se acostumará ao fato de que praticamente qualquer caractere ou palavra que você digita terá um significado especial. Por exemplo, você verá muitas palavras-chave em C#, como class, namespace, public e muito mais . Você também verá que o compilador garante que você esteja usando essas palavras-chave, bem como suas próprias variáveis e métodos, da maneira correta. C# é uma linguagem bastante rigorosa e o compilador irá ajudá-lo a certificar-se de que tudo está inserido da maneira que deveria ser. No entanto, você tem uma única possibilidade de escrever o que quiser, graças ao conceito de comentários de código.

Você pode já ter experimentado comentários em algum código visto, seja C# ou qualquer outra linguagem de programação - o conceito de comentários no código é bastante universal. A maneira como eles são escritos varia muito, então vamos dar uma olhada no tipo de comentário que você pode usar em seu código C#.

Comentários de linha única

O tipo mais básico de comentário em C# é o comentário de linha única. Como o nome indica, transforma uma única linha em um comentário - vamos ver como fica:

// My comments about the class name could go here...
class Program
{
    ......

Então é isso: prefixe suas linhas com duas barras (//) e seu texto vai de algo que o compilador irá verificar e reclamar, para algo que o compilador ignora completamente. E enquanto isso se aplica apenas à linha prefixada, você está livre para fazer o mesmo na próxima linha, essencialmente usando comentários de linha única para criar várias linhas de comentário:

// My comments about the class name could go here...
// Add as many lines as you would like
// ...Seriously!
class Program
{
    ...... 

Comentários de várias linhas

Caso você queira escrever várias linhas de comentários, talvez faça mais sentido usar a variante de comentário de várias linhas oferecida pelo C #. Em vez de ter que prefixar todas as linhas, basta digitar uma sequência de caracteres de início e parada - tudo é tratado como comentários:

/*  
My comments about the class name could go here...  
Add as many lines of comments as you want  
    ...and use indentation, if you want to!  
*/  
class Program  
{
    ......

Use a seqüência inicial de barra-asterisco (/ *), escreva o que quiser, em múltiplas linhas ou não, e então finalize tudo com a seqüência final de asterisco-avançar-barra (* /). Entre esses marcadores, você pode escrever o que quiser.

Como acontece com praticamente qualquer outro assunto relacionado à programação, o uso de vários comentários de linha única ou um comentário de várias linhas é frequentemente debatido. Pessoalmente, eu uso ambos, para várias situações - no final, tudo depende de você!

Comentários da documentação

Os comentários da documentação (às vezes chamados de Comentários da documentação XML) parecem com comentários regulares, mas com XML incorporado. Assim como com comentários regulares, eles vêm em duas formas: linha única e multi-linha. Você também os escreve da mesma maneira, mas com um caractere extra. Portanto, os comentários de documentação XML de linha única usam três barras (///) em vez de duas e a variante de várias linhas obtém um asterisco extra adicionado no delimitador inicial. Vamos ver como fica:

class User
{
    /// <summary>
    /// The Name of the User.
    /// </summary>
    public string Name { get; set; }

    /**
    * <summary>The Age of the User.</summary>
    */
    public string Age { get; set; }
}

Aqui você pode ver as duas variantes - single-line e multi-line. O resultado é o mesmo, mas a primeira variante costuma ser a mais usada para comentários de documentação.

Documentar seus tipos e seus membros com comentários de documentação é um assunto muito grande e, portanto, será abordado com mais profundidade em um artigo posterior, mas agora você sabe como eles estão!

Comentários de código & a lista de tarefas

Se você estiver usando o Visual Studio, poderá obter ajuda para rastrear seus comentários de código. Na janela Lista de Tarefas (acessá-lo no menu Visualizar > Lista de Tarefas ), seus comentários aparecerão se usarem a sintaxe especial, mas muito simples, da Lista de Tarefas:

//TODO: Change "world" to "universe"
Console.WriteLine("Hello, world!");
//HACK: Don't try this at home....
int answerToLife = 42;

Portanto, se o comentário de linha única for imediatamente seguido por TODO ou HACK, ele aparecerá na Lista de Tarefas do Visual Studio, desta forma:

E há mais tipos - dependendo da versão do Visual Studio que você estiver usando, ele responderá a alguns ou todos os seguintes tokens de comentário:

• TODO
• HACK
• NOTE
• UNDONE

Você mesmo pode adicionar seus tokens, se você quiser - basta seguir os passos descritos neste artigo.

Resumo

Os comentários de código são extremamente úteis para documentar seu código ou para o propósito de deixar pistas para você mesmo ou para seus colegas em potencial sobre como as coisas funcionam. Como benefício adicional, eles são ótimos quando você precisa testar algo rapidamente - basta copiar uma linha e comentar a linha original e você pode ver como ela funciona agora. Se você não estiver satisfeito com o resultado, basta excluir a nova linha e descomentar a linha original e voltar ao ponto de partida.

E não se preocupe com o usuário final bisbilhotando seus comentários - eles são, como já mencionado, completamente ignorados pelo compilador e, portanto, não incluídos em seu arquivo DLL ou EXE final. Os comentários de código são o seu espaço livre pessoal durante a programação, portanto, use-o da maneira que desejar.