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
ogets
depende de los accesores de propiedad.Respuestas:
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:
Cuando intellisense se abre para acceder a una de estas propiedades, no hay indicación de cuáles se pueden escribir, leer o ambas:
Del mismo modo, al ver la documentación tampoco estamos muy seguros:
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.
fuente
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.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:
La otra opción que enumeres sería.
vs
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).
fuente
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.
fuente
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.
fuente