Estoy tratando de hacer un punto de documentar mejor mi código, especialmente cuando se trata de los comentarios XML sobre los miembros de la clase, pero a menudo simplemente se siente tonto.
En el caso de los controladores de eventos, la convención de nomenclatura y los parámetros son estándar y claros:
/// <summary>
/// Handler for myCollection's CollectionChanged Event.
/// </summary>
/// <param name="sender">Event Sender</param>
/// <param name="e">Event Arguments</param>
private void myCollection_CollectionChanged(object sender, NotifyCollectionChangedEventArgs e)
{
// actual code here...
}
Con frecuencia, también tengo propiedades simples que se nombran claramente (IMO) para que el resumen sea redundante:
/// <summary>
/// Indicates if an item is selected.
/// </summary>
public bool ItemIsSelected
{ get { return (SelectedItem != null); } }
No siento que tales comentarios no agreguen ninguna información que la declaración en sí no transmita. La sabiduría general parece ser que un comentario que repita el código es mejor dejarlo sin escribir.
Obviamente, la documentación XML es más que simples comentarios de código en línea, e idealmente tendrá una cobertura del 100%. ¿Qué debería estar escribiendo en tales casos? Si estos ejemplos están bien, ¿qué valor agregan que es posible que no aprecie ahora?