Estou procurando uma recomendação de uma prática recomendada para comentários XML em C #. Quando você cria uma propriedade, parece que a documentação XML esperada possui o seguinte formato:
/// <summary>
/// Gets or sets the ID the uniquely identifies this <see cref="User" /> instance.
/// </summary>
public int ID {
get;
set;
}
Mas como a assinatura da propriedade já informa quais operações estão disponíveis para os clientes externos da classe (nesse caso, são ambas get
e set
), sinto que os comentários são muito faladores e que talvez o seguinte seja suficiente:
/// <summary>
/// ID that uniquely identifies this <see cref="User" /> instance.
/// </summary>
public int ID {
get;
set;
}
A Microsoft usa o primeiro formulário, portanto parece uma convenção implícita. Mas acho que o segundo é melhor pelas razões que afirmei.
Entendo que essa citação é adequada para ser marcada como não sendo construtiva, mas a quantidade de propriedades que se tem que comentar é enorme e, portanto, acredito que esta questão tem o direito de estar aqui.
Aprecio todas as idéias ou links para as práticas recomendadas oficiais.
fonte
gets or sets
ougets
dependendo deles .Respostas:
A assinatura pode informar a outras partes do código quais operações estão disponíveis; no entanto, eles não são mostrados claramente ao codificador enquanto ele está trabalhando e a documentação XML é destinada às pessoas para consumir e não um compilador.
Veja esta classe, por exemplo:
Quando o intellisense é puxado para acessar uma dessas propriedades, não há indicação de quais podem ser gravadas, lidas ou ambas:
Da mesma forma, ao visualizar a documentação, também não temos certeza:
Como tal, adicionamos os get ou sets , gets ou sets para facilitar o programador ao escrever o código. Certamente não seria escrever um grande bloco de código que lê e processa alguns dados apenas para descobrir que você não pode gravar esses dados de volta na propriedade conforme o esperado.
fonte
get
apenas no contexto atual. Não é muito conveniente dobrar a documentação para se ajustar a um ambiente de desenvolvimento específico. Ainda acho que o Visual Studio e o C # estão tão intimamente relacionados que essa pode ser a solução certa.StyleCop usa a
Gets or Sets ...
notação que aplica com a regra SA1623 .A página vinculada lista outro caso que você não listou:
A outra opção que você listaria seria.
vs
Que não fornecem informações sobre a dica Intellisense que a propriedade é somente leitura, você poderia vir acima com uma convenção para este caso também, mas
Gets ...
,Gets or Sets...
faz o trabalho muito bem imo.Também há outros variantes listados na regra StyleCop que são claras usando o,
Gets or Sets...
mas podem não existir.Além disso, ao gerar documentação a partir de algo como Doxygen ou Sandcastle, a notação completa documentaria melhor a API (por exemplo).
fonte
A única vez em que adiciono informações sobre a obtenção e a configuração de uma propriedade nos comentários XML é quando ela não se comporta como o esperado (obtenção e configuração públicas diretas).
Se são privados ou contêm lógica adicional, eu os mencionei, caso contrário, apenas documento a intenção da propriedade.
fonte
Eu ficaria mais feliz com a versão mais detalhada.
O outro é como ter um comentário do "contador de incremento" depois de, bem, incrementar uma variável do contador.
É óbvio que existe um Get e Set. Se você tivesse um setter privado, seria óbvio que você teria a palavra-chave privada.
Os comentários devem agregar valor, não apenas ser uma versão de comentário do que realmente é o código.
fonte