Em qualquer ambiente profissional, documentar adequadamente seu código com comentários é necessário para uma legibilidade de longo prazo. Para código .NET, a Microsoft fornece um sistema para comentários baseados em XML que fornecem suporte IDE aprimorado.
O que são comentários XML?
Essencialmente, os comentários XML são um tipo especial de comentário denotado por uma barra tripla (///) e tags XML para dar alguma estrutura ao comentário. Por exemplo, um comentário de resumo simples seria semelhante a este:
![]()
O ponto disso é que, quando você for usar esse método em outro lugar em seu código, o Visual Studio poderá examinar o XML e adicionar algumas informações diretamente no pop-up do Intellisense. Este sistema funciona para todos os tipos de tipos e pode até ser usado para documentar valores de retorno e parâmetros individuais. E, ao distribuir o assembly, você pode distribuir o arquivo XML com ele para habilitar esses mesmos recursos para qualquer pessoa que use sua biblioteca de classes. Isso também permite o uso fácil de geradores de documentação estática como DocFX e Sandcastle.
Surpreendentemente, esse recurso é principalmente uma coisa do .NET. Nada impede que você use a prática com outros idiomas, mas é algo que a Microsoft suporta bem para seus idiomas e editores, e outros idiomas geralmente não têm suporte adequado para isso. Adoraríamos ver o suporte expandido para outros idiomas e editores, pois é universalmente útil.
É muito simples de usar. Simplesmente pressione a tecla de barra três vezes (///) acima de um método, classe ou outro tipo, e o Visual Studio irá inserir um modelo para você digitar. Isso evita o incômodo de digitar manualmente, o que significa que realmente não há razão para não usar esses comentários tradicionais de barra dupla .
![]()
Se o seu método tiver um tipo de retorno ou parâmetros, o Visual Studio irá gerar campos para eles também. Você verá seus comentários quando for usar o método:
![]()
O padrão suporta vários tipos de tags:
é mostrado no Intellisense sempre que você usa o método. - é como um resumo, mas não aparece no Intellisense (útil para escrever documentação estendida).
- documenta o tipo de retorno.
- permite que os desenvolvedores saibam quais exceções o método pode lançar.
- é como retornos, mas para propriedades de classe.
- mostra um exemplo de código para a documentação (use com
). - e geram links clicáveis para outros métodos, geralmente usados para documentar sobrecargas.
- permite o uso de listas para ordenar os elementos.
Você pode ler a documentação da Microsoft sobre o padrão de comentários XML para obter mais informações.



