Estou tentando documentar melhor meu código, especialmente quando se trata de comentários XML sobre os membros da classe, mas muitas vezes parece bobagem.
No caso de manipuladores de eventos, a convenção de nomenclatura e os parâmetros são padrão e claros:
/// <summary>
/// Handler for myCollection's CollectionChanged Event.
/// </summary>
/// <param name="sender">Event Sender</param>
/// <param name="e">Event Arguments</param>
private void myCollection_CollectionChanged(object sender, NotifyCollectionChangedEventArgs e)
{
// actual code here...
}
Também frequentemente tenho propriedades simples que são (IMO) nomeadas claramente para que o resumo seja redundante:
/// <summary>
/// Indicates if an item is selected.
/// </summary>
public bool ItemIsSelected
{ get { return (SelectedItem != null); } }
Eu não acho que esses comentários não adicionem nenhuma informação que a declaração em si ainda não transmita. A sabedoria geral parece ser que um comentário que repete o código é melhor não ser escrito.
Obviamente, a documentação XML é mais do que apenas comentários regulares de código embutido e, idealmente, terá 100% de cobertura. O que devo escrever nesses casos? Se esses exemplos estão corretos, que valor eles acrescentam que talvez eu não esteja gostando agora?
fonte
GetData()
você faz"? Porque, éGets the data
claro!Respostas:
Os comentários de documentos XML destinam-se a membros públicos.
O aviso do compilador afirma claramente isso:
Você só deve adicionar comentários XML a membros privados se esses membros ainda não estiverem evidentes em seus nomes.
fonte
Pura opinião aqui, então aceite pelo que vale a pena.
Eu odeio comentários xml supérfluos. Duplamente para os fantasmas no estilo doc, que simplesmente adicionam espaços ao nome do método / propriedade. Não agrega valor e simplesmente atrapalha minha visão do código real.
Se algo precisar de esclarecimento, com certeza, comente. No entanto, muita clareza pode ser transmitida por pequenos métodos focados com nomes significativos. Não comente o código se puder melhorá-lo e tornar o comentário desnecessário.
Nem me inicie no uso desnecessário
this.
eMe.
.Como uma observação lateral, eu adoraria ter um complemento do Visual Studio que permita alternar a visibilidade dos comentários xml. (dica, dica)
fonte
this.
coisa pode ter começado porque, por algum motivo, as diretrizes oficiais da Microsoft recomendaram o uso exato da mesma convenção de nomenclatura para variáveis locais eprivate
variáveis de instância . Esse é um estilo terrivelmente defeituoso, IMO - em alguns casos, você está a um dedo de distância de umaStackOverflowException
propriedadeset
s ou estáMyProperty = MyProperty;
fazendo com que um campo seja inicializado com zero em vez de um parâmetro de construtor, e até a Microsoft continuou a usarm_
internamente a maior parte do tempo .Em um membro público, os documentos XML devem ser bastante detalhados e completos, como o @SLaks mencionou.
No entanto, eles também podem ser realmente úteis para membros privados, protegidos ou internos, porque o Visual Studio preencherá o intellisense e ajudará as dicas de ferramentas com os comentários dos documentos XML.
Isso significa que:
Pode ser documentação perfeitamente suficiente, mas:
Será muito mais fácil ver rapidamente de outras partes do seu código.
Geralmente nos comentários XML públicos que estou escrevendo para algum usuário externo da API e nos comentários XML internos que estou escrevendo para mim ou para outros membros da minha equipe.
Ignorar descrições de parâmetros é provavelmente uma má ideia para o primeiro e bom para o último.
Eu acrescentaria (principalmente nos documentos públicos da API) sempre incluir
get
ou não asset
propriedades:Não é óbvio pelo intellisense do C # se está disponível
get
ouset
não, mas colocá-lo no comentário XML significa que você pode ver rapidamente a dica de ferramenta.fonte
public get
apenas umainternal set
propriedade? Como você comenta isso? :-)get
XML e documentá-loset
com//
comentários regulares .