C# XML Comments
Em Programação | 09/03/2010 01:57, atualizado em 09/03/2010 02:56
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:
- Artigo na MSDN explanado usos e possibilidades dos XML Comments.
- Sandcastle, ferramenta para geração de arquivos de help com base em XML Comments.
- Sandcastle Help File Builder, interface gráfica para facilitar a configuração do Sandcastle.
André!
Como sempre realiza uma boa explicação com muito bom humor! =D
Realmente, os comentários além de ajudar, deixam o código elegante para que outros programadores possam entender e utilizar.
Um abraço!
ResponderMuito obrigado, cara Juliana!
Com certeza comentários são fundamentais para tornar o código mais legível não só a outros programadores, mas também a nós mesmos - vai me dizer que depois de uma semana de trocentas missões você ainda lembra daquela obscura implementação feita numa classe de um componente de um subsistema utilizado no módulo de uma aplicação a qual você nem exatamente sabe qual é?
ResponderÉ verdade, penso assim também, não quer dizer que uma etapa do projeto terminou que jamais terá que ser utilizada por alguém ou por eu mesma, isso é quase impossível.
ResponderDe fato! "Comentar" é a melhor forma de documentação de código.
ResponderRealmente, um código comentado é a MELHOR coisa que pode-se existir na programação.
É horrível pegar um código de '1800000' linhas e se deparar com métodos xizes, zes, etc kk....e nem ao menos ter um coment (que é tão simples de fazer) explicando.
Excelente post, parabéns!
ps. o que seria de mim sem o Visual Studio??
ResponderCódigo comentado + Visual Studio = ótima programação! :P
Realmente é assustador pegar algum código gigantesco com poucas ou mesmo nenhuma linha de comentário; só torna o processo de compreensão do "texto" ainda mais complicado do que costumeiramente já é - entender coisas feitas por outros ou mesmo por nós após um longo período de esquecimento e sem comentários (ou porque não, "documentação") é um grande exercício de paciência e multiplicação das sinapses cerebrais.
Responder