Quais são as virtudes de usar comentários XML no .NET?

Question

Não consigo entender as virtudes do uso de comentários XML.Eu sei que eles podem ser convertidos em uma boa documentação externa ao código, mas o mesmo pode ser alcançado com a sintaxe DOxygen muito mais concisa.Na minha opinião os comentários XML estão errados porque:

1. Eles ofuscam os comentários e o código em geral.(Eles são mais difíceis de ler pelos humanos).
2. Menos código pode ser visualizado em uma única tela, porque "resumo" e "/resumo" ocupam linhas adicionais.
3. (removido)

Quais poderiam ter sido as razões pelas quais o XML foi preferido no .NET em vez da simples sintaxe DOxygen?

Answer 1

Não há realmente uma resposta correta aqui IMO. Nenhum dos sistemas é "melhor" do que o outro na realidade - ambos fazem o mesmo trabalho no final, o que permite que você gere documentação de código.

A saída final pode ser formatada exatamente da mesma maneira para cada um deles, e eles têm praticamente a mesma funcionalidade em termos de quais rótulos etc. eles suportam, então é realmente uma escolha pessoal aqui.

Pessoalmente, acho que os comentários XML são muito mais legíveis humanos, muito mais lógicos e simplesmente fáceis de usar - mas isso é com a vantagem adicional de ter o Visual Studio gerar automaticamente stubs para eu apenas preencher, e o excelente apoio que ele tem para que tenha sido para Colapsando -os para que eles não ocupem muito espaço na tela. Estou certo de que alguém que vem de uma edição de fundo em VI ou Some_Other_ide terá uma opinião diferente, mas também não há vantagem real.

Então, eu diria que realmente depende do que você está usando e do que você e sua equipe estão acostumados a usar.

Agora, se você está perguntando por que a Microsoft optou por se integrar tão firmemente com o comentar o XML no Visual Studio, essa é uma pergunta diferente. Provavelmente, é devido aos fatos que: seria mais simples para eles implementarem no VS (pois podem reutilizar o código existente para gerar/ler os comentários e construir o Intellisense etc.), eles têm uma tendência para aderir aos "padrões "De qualquer forma (seja eles próprios ou no setor) e também licenciando razões, conforme mencionado por Jeff.

Apenas para acrescentar que o produto que a Microsoft está usando no VS é chamado de "Sandcastle", que é uma ferramenta interna de geração XML Doc. Tem sua própria página wiki @ http://docproject.codeplex.com/wikipage

Answer 2

1. O ide pega os comentários e os mostra ao usar esse método.
2. Todos que programam C# provavelmente estão familiarizados com o sistema de comentários XML.Há menos o que aprender para um novo contratado.

Não estou dizendo que o DOxygen não seja melhor, apenas que o sistema de comentários xml é mais familiar para todos, e isso é muito útil.É apenas uma coisa a menos que você precisa treinar um novo contratado para fazer.

No que diz respeito a deixar variáveis ​​sem comentar.O que pode ser óbvio para você, não será para outra pessoa (ou para você 6 meses depois).

Ok, agora acho que entendi o que você está perguntando.

1. Comentários ofuscantes.O código de cores ajuda.Pessoalmente, passo rapidamente o texto cinza e leio apenas o que está verde, a menos que precise ler o texto xml.(pelo menos nas minhas configurações).

2. Temos monitores grandes, então temos mais código na tela em geral.(É mais barato comprar um monitor grande do que retreinar as pessoas em geral).A outra coisa sobre isso também é que aposto que você está olhando ativamente apenas uma função por vez; portanto, se toda a função couber em uma página, você provavelmente não estará sofrendo muito por não ver mais código.Agora, se as funções forem longas, posso ver que isso é um problema.

3. Colocamos os comentários resumidos em uma única linha quando possível (assumindo que não seja muito grande).Isso reduz o espaço usado.

4. Não sei se o DOxygen faz isso, mas você pode recolher os comentários para que fiquem fora do caminho.

Answer 3

O trabalho principal da documentação XML é não Para gerar documentação. É para fornecer boas informações do Intellisense para o cliente da sua classe. Envie o arquivo .xml gerado junto com sua montagem.

Answer 4

As virtudes de usar comentários XML no .NET

Eles são apoiados nativamente pelo compilador C# e pelo Visual Studio, fornecendo um único local para documentar sua API para uso em documentação impressa, online e IntelliSense.

Este artigo da revista MSDN declara o seguinte:

Em todos os projetos, há alguém que não está feliz com a documentação. Os líderes da equipe desejam mais comentários na fonte, os escritores técnicos querem mais informações escritas sobre o design do código, a garantia da qualidade deseja ver especificações funcionais e assim por diante. Se todos esses documentos estiverem realmente escritos, você ainda terá a batalha de manter todos eles sincronizados.

Embora o formato não seja necessariamente ideal, os comentários da documentação XML fornecem uma sintaxe rica, de modo que isso possa ser alcançado.

Por que não suportar doxygen em C# em vez disso?

Quanto ao motivo pelo qual o sistema XML existente foi escolhido sobre doxygen, eu suspeitaria que isso é principalmente porque Doxygen é liberado sob o Gpl o que significaria Termos da GPL.

Answer 5

O que eu acho ainda mais impressionante é a popularidade do Ghostdoc plugar. Se você pode gerar automaticamente um comentário com base em um nome de método, por que o comentário?

Steve Yegge diz que comentar sobre comentários é o sinal de um programador novato, tenho dificuldade em discordar dele.

Answer 6

Você não tenho para usá -los em seus projetos.

Eles são uma padrão que é integrado ao Visual Studio e se você usar o StyleCop, eles podem ser aplicados. Então esta é a virtude aqui.

No entanto, se você decidir usar doxygen, não há nada para impedi -lo. Apenas verifique se você é consistente.