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:

 Comentário resumido simples no código .NET.

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 .

Pressione a tecla barra três vezes (///) acima de um método, classe ou outro tipo e o Visual Studio irá inserir um modelo para digitar.

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:

Visual Studio irá gerar campos para tipos de retorno ou parâmetros também.

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.

Adicione ao Google Notícias