¿Qué debo incluir en los comentarios de la documentación XML?

13

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?

    
pregunta mbmcavoy 14.09.2011 - 00:24

3 respuestas

9

Los comentarios de documentos XML están destinados a miembros públicos.

La advertencia del compilador lo indica claramente:

  

Falta el comentario XML para el tipo visible públicamente o el miembro 'Type_or_Member'

Solo debes agregar comentarios XML a miembros privados si esos miembros no son evidentes por sus nombres.

    
respondido por el SLaks 14.09.2011 - 01:51
5

Opinión pura aquí, así que tómala por lo que vale.

Yo odio comentarios xml superfluos. Doblemente así para los de estilo fantasma doc que simplemente agregan espacios al nombre del método / propiedad. No agrega ningún valor y simplemente desordena mi vista del código real.

Si algo necesita aclaración, por favor, coméntalo. Sin embargo, una gran cantidad de claridad puede ser transmitida por métodos enfocados pequeños con nombres significativos. No comente el código si puede mejorarlo y hacer que el comentario sea innecesario.

Ni siquiera me refiero al uso innecesario de this. y Me. .

Como nota al margen, me encantaría tener un complemento de Visual Studio que me permita alternar la visibilidad de los comentarios xml. (pista, pista)

    
respondido por el codeConcussion 14.09.2011 - 18:02
1

En un miembro público, los documentos XML deben ser bastante detallados y completos, como lo ha mencionado @SLaks.

Sin embargo, también pueden ser realmente útiles en miembros privados, protegidos o internos, ya que Visual Studio completará el conocimiento inteligente y las sugerencias de ayuda con los comentarios de la documentación XML.

Esto significa que:

// describe what this does
private void DoSomething() 
{
    // or describe it here...

Puede ser documentación perfectamente suficiente, pero:

/// <summary>describe what this does</summary>
private void DoSomething() 
{

Será mucho más fácil verlo rápidamente desde otra parte de tu código.

En general, en los comentarios XML públicos que estoy escribiendo para un usuario externo de la API, y en los comentarios XML internos que estoy escribiendo para mí o para otros en mi equipo.

Omitir las descripciones de los parámetros es probablemente una mala idea para el primero y está bien para el segundo.

Yo agregaría (especialmente en documentos públicos de la API) siempre incluya si get o set en las propiedades:

/// <summary>Gets a value indicating whether an item is selected.</summary>
public bool ItemIsSelected
{ 
    get { return SelectedItem != null; } 
}

No es obvio a partir de la inteligencia de C # si están disponibles get o set , pero ponerlo en el comentario XML significará que se puede ver de un vistazo en la información sobre herramientas.

    
respondido por el Keith 15.09.2011 - 09:44

Lea otras preguntas en las etiquetas