Voltar

C# XML Comments

Em Programação | 09/03/2010 01:57, atualizado em 09/03/2010 02:56 Good Comments

Comentar o código é uma arte - e uma necessidade a qual muitos programadores ignoram.

Sem comentários (e sem trocadilhos), um bloco de códigos pode tornar-se tão inteligível quanto hieróglifos egípcios: você até sabe o que está ali; mas não necessariamente compreende o que aquilo quer dizer.

Comentários para comentar seu código

No Visual Studio, desde suas primeiras versões na plataforma .Net, determinadas tags XML podem ser utilizadas para criação de comentários sobre classes e seus membros, com possibilidade de geração de um help completo com base em tais comentários.

Além de tornar o código mais facilmente interpretável, tais comentários não obstruem a visualização dos membros de classes pois a IDE permite que sejam fechados, ocupando pouco espaço no editor.

Listinha de tags XML

Para tornar a sua vida e a minha mais simples (afinal, eu também uso meu site como fonte de consulta), seguem abaixo as principais tags XML de comentários disponíveis no Visual Studio, com breves descrições sobre cada uma delas.

Recomenda-se que as tags mais comuns (<summary>, <param name=""> e <returns>) sejam sempre preenchidas para facilitar o entendimento do código e geração de documentações automatizadas (vide mais abaixo).

///  <summary>
///     Descrição do membro (propriedade, método, enumeração, etc.).
///     <paramref>Nome do parâmetro (referência a um parâmetro)</paramref>
///     <c>Uma linha de código</c>
///     <code>
///      Um bloco de código
///    	</code>
///    <see cref="Membro da classe">Rótulo</see>
///    <see cref="Membro da classe" />
///    <see href="URL">Rótulo</see>
///    <see langword="null|sealed|static|abstract|virtual|true|false"/>
///    <list type="bullet"|"number"|"table"|"definition">
///      <listheader>
///        <term>Cabeçalho de valores(quando type="table")</term>
///        <description>Cabeçalho de descrições</description>
///      </listheader>
///      <item>
///        <term>Valor</term>
///        <description>Descrição</description>
///      </item>
///    </list>
///  </summary>
///  <value>Descreve os valores GET/SET de propriedades.</value>
///  <param name="Nome do parâmetro">Descrição do parâmetro.</param>
///  <exception cref="System.Exception">
///    Descrição de possíveis erros a serem gerados pelo membro.
///  </exception>
///  <remarks>
///     Comentários adicionais sobre o membro.
///  </remarks>
///  <example>
///     Exemplo de utilização do método.
///  </example>
///  <seealso cref="Classe">Rótulo (link para membro de classe)</seealso>
///  <seealso href="URL">Rótulo (link para uma URL)</seealso>
///  <returns>Descrição dos dados de retorno.<returns>

Ao infinito e além

Caso tenha alguma dúvida, curiosidade, trauma ou angústia sobre o artigo, ou apenas deseja elogiá-lo, utilize o espaço de comentários mais abaixo para entrar em contato.

Seguem abaixo alguns links interessantes:

Comentários
Comentar
Campos marcados com * são obrigatórios. Seu e-mail não será exibido.
*
*
*
Captcha *
CATEGORIAS AO TOPO E ALÉM LUGARES PARA IR
Topo

“Perfection (in design) is achieved not when there is nothing more to add, but rather when there is nothing more to take away.” - Design quote