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 get
y 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.
gets or sets
o gets
depende de los accesores de propiedad.