¿Es necesario el "Obtiene o establece ..." en la documentación XML de propiedades?

19

Estoy buscando una recomendación de una mejor práctica para comentarios XML en C #. Cuando crea una propiedad, parece que la documentación XML esperada tiene la siguiente forma:

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

Pero dado que la firma de la propiedad ya le dice qué operaciones están disponibles para los clientes externos de la clase (en este caso son ambas gety set) siento que los comentarios son demasiado habladores y que tal vez lo siguiente sería suficiente:

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

Microsoft usa el primer formulario, por lo que parece que es una convención implícita. Pero creo que el segundo es mejor por las razones que dije.

Entiendo que esta pregunta es un experto para ser marcado como no constructivo, pero la cantidad de propiedades que uno tiene que comentar es enorme, por lo que creo que esta pregunta tiene derecho a estar aquí.

Apreciaré cualquier idea o enlace a las prácticas oficiales recomendadas.

Tomás
fuente
Honestamente, lo único que me da el comentario que no está en el código (suponiendo que sea miembro del Usuario) es que la identificación es única. así que nada de eso es "necesario".
jk.
@Tomas: ¿has instalado el complemento GhostDoc ? generará buenos comentarios XML para usted si utiliza buenos nombres de propiedad para comenzar y automáticamente coloca gets or setso getsdepende de los accesores de propiedad.
Trevor Pilley
@Trevor: lo tengo instalado. Estaba pensando si debería cambiar sus plantillas y eliminar "Gets or sets" o no :). Sin embargo, es un gran complemento.
Tomas
Bienvenido al mundo de la indocumentación .
Coronel Panic

Respuestas:

28

La firma puede indicarle a otras piezas de código qué operaciones están disponibles; sin embargo, no se muestran claramente al codificador ya que él o ella está trabajando y la documentación XML está destinada a que las personas la consuman y no a un compilador.

Tome esta clase por ejemplo:

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; }
}

Cuando intellisense se abre para acceder a una de estas propiedades, no hay indicación de cuáles se pueden escribir, leer o ambas:

ingrese la descripción de la imagen aquí

Del mismo modo, al ver la documentación tampoco estamos muy seguros:

ingrese la descripción de la imagen aquí ingrese la descripción de la imagen aquí ingrese la descripción de la imagen aquí

Como tal, agregamos el gets o sets , gets o sets para que sea más fácil para el programador al escribir el código. Ciertamente no sería escribir un gran bloque de código que lea y procese algunos datos solo para descubrir que no puede volver a escribir esos datos en la propiedad como se esperaba.

ingrese la descripción de la imagen aquí

Miguel
fuente
Gracias por una respuesta completa. Creo que, lamentablemente, estas son limitaciones del IDE de Visual Studio. Lo he pensado y creo que el intellisense podría mostrarle qué propiedades son, por ejemplo, get-solo en el contexto actual. No es muy conveniente doblar la documentación para que se ajuste a un entorno de desarrollo particular. Aún así, creo que Visual Studio y C # están tan estrechamente relacionados que esta podría ser la solución correcta.
Tomás
1
@Tomas Estoy de acuerdo en que Visual Studio debería hacer más una distinción. Ciertamente, me complace darme una línea roja ondulada en el momento en que uso la propiedad de manera incorrecta.
Mike
2

StyleCop usa la Gets or Sets ...notación que aplica con la regla SA1623 .

La página vinculada enumera otro caso que no ha enumerado:

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

La otra opción que enumeres sería.

/// <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 no proporcionaría información sobre la pista Intellisense que la propiedad es de sólo lectura, se podía llegar a una convención para este caso también, pero Gets ..., Gets or Sets...hace el trabajo muy bien imo.

También hay otras variantes enumeradas en la regla StyleCop que son claras mediante el uso de, Gets or Sets...pero podrían no estarlo.

Además, al generar documentación de algo como Doxygen o Sandcastle, la notación completa documentaría mejor la API (por ejemplo).

NikolaiDante
fuente
2

La única vez que agrego información sobre la obtención y configuración de una propiedad en los comentarios XML es cuando no se comporta como se esperaba (get y set público directo).

Si son privadas o si contienen lógica adicional, las menciono; de lo contrario, solo documento la intención de la propiedad.

CLandry
fuente
1

Estaría más feliz con la versión más detallada.

El otro es como tener un comentario de "contador de incremento" después de, bueno, incrementar una variable de contador.

Es obvio que hay un Get and Set. Si tuviera un setter privado, sería obvio ya que tendría la palabra clave privada.

Los comentarios deben agregar valor, no solo ser una versión de comentarios de lo que realmente es el código.

ozz
fuente