C# XML Comentarios: ¿Cuántas referencias de <see ... /> en comentarios XML son útiles?

Question

En nuestra compañía escribimos comentarios Xml excesivos. Un método típico se ha documentado a ser así:

/// <summary> 
/// Determines whether this <see cref="IScheduler"/> contains a specific <see cref="ISchedule"/>. 
/// </summary> 
/// <param name="schedule">The <see cref="ISchedule"/> to locate in this <see cref="IScheduler"/>.</param> 
/// <returns> 
/// Returns <see langword="true"/> if <paramref name="schedule"/> is found in this <see cref="IScheduler"/>; otherwise, <see langword="false"/>. 
/// </returns> 
bool Contains(ISchedule schedule); 

/// <summary> 
/// Removes and <see cref="IDisposable.Dispose"/>s the first occurrence of a specific <see cref="ISchedule"/> 
/// from this <see cref="IScheduler"/>. 
/// </summary> 
/// <param name="schedule">The <see cref="ISchedule"/> to remove from this <see cref="IScheduler"/>.</param> 
/// <exception cref="System.ArgumentNullException">Is thrown when the parameter schedule is null.</exception> 
/// <exception cref="System.ArgumentException">Is thrown when the <see cref="ISchedule"/> is not found in this <see cref="IScheduler"/> or was of the wrong type.</exception> 
void Remove(ISchedule schedule); 

Como se puede ver casi cada sustantivo que puede ser referenciado usando una etiqueta <see cref>.
Esto me parece demasiado. La mayoría de nuestros archivos de código están tan explotados con tales comentarios. Hace que la sección de comentarios sea casi ilegible.

¿Qué opinas? ¿Te gusta este tipo de documentación en el código o no?

Como de costumbre, creo que no hay una respuesta en blanco y negro para ese tipo de pregunta, es por eso que lo hice wiki.

EDITAR:
Mi pregunta no fue si las etiquetas see-ref en sí son útiles por defecto. Está claro que los enlaces generados en el archivo .chm (o cualquier otro tipo de documento generado) son muy útiles. Mi pregunta era si es realmente útil etiquetar cada aparición de cada nombre "enlazable" en los comentarios.
Utilizamos Sandcastle para generar el docu todas las noches. Lamentablemente, es muy poco utilizado por otros desarrolladores, pero ese es otro problema.

Answer 1

El objetivo de todo esto es que cuando se utiliza algo como Sandcastle para generar documentos HTML o CHM para la biblioteca, esos documentos obtienen navegación hipervinculada entre los objetos. Entonces, la pregunta es, cuando usas MSDN, ¿te parece útil poder hacer clic en un nombre de clase? ¿Lo has dirigido a la ayuda para esa clase, o estás bien para copiarlo y pegarlo en el campo de búsqueda?

Sí, aumenta el código (aunque los comentarios se pueden contraer), pero si realmente envía la documentación a otros, es bastante útil.

Answer 2

Hay un motivo particular para este tipo de comentarios: se pueden usar para generar documentación o para agregar información adicional para autocompletar. Estoy de acuerdo en que son excesivamente prolijas y difíciles de leer para la mayoría de las situaciones, pero son buenas para agregar a una interfaz que expondrá externamente.

Recomendaría utilizar un editor que le permita activar y desactivar los comentarios.

Algunos idiomas le permiten almacenar comentarios como metadatos sobre variables y funciones, lo cual es una buena alternativa.

Answer 3

Personalmente, creo que lo que tienes es un poco exagerado.

El propósito de las referencias "ver" es proporcionar una buena vinculación entre los temas en la documentación de ayuda generada después del análisis.

En su caso, sus bibliotecas específicas del negocio están referencia a elementos del lenguaje, es decir:

<see langword="true"/> 

Personalmente, creo que hipervínculos a otros objetos relacionados en su biblioteca es una característica muy útil. Hace que la lectura de la ayuda sea mucho más útil para sus usuarios.

Los hipervínculos a los elementos del lenguaje es algo que creo que debería existir solo dentro del lenguaje en sí. En el caso de una biblioteca de terceros, esto simplemente "confunde" el mensaje al colocar enlaces en todas partes. Esto hace que los enlaces buenos sean menos efectivos, ya que se ocultan en el desorden.

Sugeriría el uso liberal de enlaces a clases relacionadas en su biblioteca. Evitaría agregar hipervínculos a las clases de la biblioteca base, excepto en casos específicos donde es particularmente útil por alguna razón (rara). Vincular a "verdadero" e "IDisposable.Dispose", etc., realmente no agrega mucho valor.

Confíe en su usuario para comprender el marco base, pero enséñeles sobre su biblioteca.

Answer 4

Como dijo ctacke, es muy útil para hipervincular. Sin embargo, si no está realmente enviando documentación, todo ese etiquetado hace que la documentación sea prácticamente imposible de leer. En ese caso, la documentación es para el desarrollador (edit: INTERNAL), y si él o ella no puede leerla, está perdiendo el tiempo.

Como regla, tiendo a la primera referencia a un tipo o miembro, y dejo el resto desenlazado. Deja los comentarios bastante limpios y aún proporciona enlaces significativos.

Answer 5

Cuando está trabajando con Visual Studio, puede usar el plugin CR_Documentor (es gratis, puede obtenerlo here) para WYSiWYG-leer/escribir sus comentarios. Parece que se generó ayuda de Sandcastle o NDoc, pero se procesa sobre la marcha. Es realmente útil, y no tiene que preocuparse por los comentarios XML puros en absoluto.