O item "Obtém ou define ..." é necessário na documentação XML das propriedades?

19

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 gete 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.

Tomas
fonte
honestamente, a única coisa que o comentário me dá que não está no código (supondo que este seja um membro do usuário) é que o ID é único. portanto, nada disso é "necessário".
jk.
@Tomas - você instalou o plugin GhostDoc ? ele gerará bons comentários XML para você se você usar bons nomes de propriedades para começar e colocar automaticamente os acessadores de propriedades gets or setsou getsdependendo deles .
Trevor Pilley 28/03
@ Trevor - eu tenho instalado. Eu só estava pensando se eu deveria alterar seus modelos e remover o "Obtém ou define" ou não :). É um ótimo plugin embora.
Tomas
Bem-vindo ao mundo da falta de documentação .
Coronel Panic

Respostas:

28

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:

public class MyClass
{
    /// <summary>
    /// The first one
    /// </summary>
    public int GetOrSet { get; set; }

    /// <summary>
    /// The second one
    /// </summary>
    public int GetOnly { get; private set; }

    /// <summary>
    /// The last one
    /// </summary>
    public int SetOnly { set; private get; }
}

Quando o intellisense é puxado para acessar uma dessas propriedades, não há indicação de quais podem ser gravadas, lidas ou ambas:

insira a descrição da imagem aqui

Da mesma forma, ao visualizar a documentação, também não temos certeza:

insira a descrição da imagem aqui insira a descrição da imagem aqui insira a descrição da imagem aqui

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.

insira a descrição da imagem aqui

Mike
fonte
Obrigado por uma resposta completa. Infelizmente, essas são limitações do IDE do Visual Studio. Eu pensei sobre isso e acho que o intellisense poderia mostrar quais propriedades são, por exemplo, getapenas 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.
Tomas
1
@ Tomas Concordo que o Visual Studio deve fazer mais distinção. Certamente, é um prazer me dar uma linha ondulada vermelha no segundo em que uso a propriedade de forma inadequada.
31513 Mike
2

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:

/// <summary>
/// Gets a value indicating whether the item is enabled.
/// </summary>
public bool Enabled
{
    get { return this.enabled; }
}

A outra opção que você listaria seria.

/// <summary>
/// ID that uniquely identifies this <see cref="User" /> instance.
/// </summary>
public int ID { get; set; }

vs

/// <summary>
/// ID that uniquely identifies this <see cref="User" /> instance.
/// </summary>
public int ID { get; }

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).

NikolaiDante
fonte
2

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.

CLandry
fonte
1

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.

ozz
fonte