XML Comentários: Para usar ou não usar?

Question

Os meus colegas de trabalho raramente (ou nunca) o uso de XML Comentários ao trabalhar em nosso software (eu não posso dizer que estou melhor). Eu vi recentemente os benefícios de usá-los, mas eles são realmente vale a pena se o código que está documentando está escrito claramente (expressiva / nomes / função variável descritivos, alguns em linha comentando)?

Obrigado!

Answer 1

comentários XML são úteis para a geração de documentação. Se o código está escrito claramente, então você não deve precisar de comentários para ajudar você a entender o código.

No entanto comentários de documentação são úteis para o usuário das classes porque ele (deverá) conter (s) uma descrição da classe ou métodos de funcionalidade, não uma descrição do código.

Answer 2

Eu acho que comentários de código são muito importantes, especialmente em métodos enfrentam públicos e propriedades. As pessoas podem dizer bem quando eles dizem o seu código é descritiva e talvez seja, mas acho que a nova cara que olha para isto:

Linker.Extract(IpoValidator validator, MeanDexIndicator Indicator)

A menos que ele entende o contexto do método, ele não pode descobrir o seu propósito. A principal questão pessoas parecem ter com os comentários são que eles não são muito úteis. Isso ocorre porque as pessoas escrever comentários ruins. Você deve falar sobre o que está acontecendo não é o que é. Eu posso ver que o método é um método de extracção, assim que comentários como:

 <Summary>Extracts The Fumble <\Summary>

são um desperdício de energia. O seguinte é melhor:

 <Summary>
 The Fumble needs to be extracted before the bopper can be used. In order for 
 extraction to work a validator and indicator need to be provided. Once extracted 
 the bopper is available in the property Linker.Bopper. On fail this 
 method will raise the CrappedOutException.
 </Summary>

Veja a diferença?

I tendem a usar apenas resumos parâmetros e retornos como todos eles show em intellisense, tudo o resto como observações e pode ser um desperdício de tempo como eles não são sempre mostrados.

Quanto ao rapaz que se recusa a atualizar seus comentários depois de mudar alguma coisa. As revisões de código deve pegar isso. Pessoalmente eu uso comentários xml sobre métodos privados e adereços dois, mas que um é escolha pessoal. Em métodos enfrentam públicos e propriedades? Eu não é opcional.

Answer 3

comentários XML são realmente úteis para APIs mesmo aqueles usados ??em um pequeno grupo.

Answer 4

Nós achar que é útil, porque vs verifica automaticamente para se certificar de que certos comentários estão lá. Além disso, qualquer novo entrando na organização que tenha usado vs antes sabe o comentários trabalho, e não temos para explicar um novo sistema de comentar código. Na ocasião geramos documentação a partir dele, mas realmente é apenas mais fácil para nós, para usá-lo porque ele preenche uma série de coisas para você (como algum parâmetro etiquetas etc).

Answer 5

Como enfrentando tanto quanto internamente código e comentários, aqui está um post por Jeffery Palermo que acabei de ler e tenho que concordar com.

Em resumo: Lotes de comentários apenas reduz a legibilidade e ajuda pouco, bons comentários podem ser muito úteis, mas aumentar o custo para manter o software e pode até causar grandes problemas quando eles não estão mantidos e dar informações falsas. Não há nenhum substituto para o código bem concebido e nomeado.

Answer 6

Não existe uma tag de anotação que é ignorado funcionalmente, mas pode ser processado por alguns XSLT para ser transformado diretamente em documentação? Comentários são bons (e eu usá-los), mas eu acho que o valor do tag anotação e a transformação direta que pode fazer superam o uso do comentário como documentação. Então, em resumo, as tags uso de anotação para a documentação para ser lido por outros, use comentários para notas para o seu auto ou 'nos bastidores' coisas (ou seja, 'OMG corrigir isso antes da explosão MUNDO!')