¿Cómo se evita la redundancia en los comentarios de la documentación?

Question

Acabamos de empezar a utilizar StyleCop y lo único que me resulta difícil es los requisitos de documentación. No quiero debatir sobre la utilidad de la herramienta, solo me pregunto si alguien tiene alguna guía o forma de pensar sobre la documentación de métodos que hace que los comentarios sean realmente útiles. Encuentro que mis comentarios a menudo contienen una gran cantidad de repetición sólo para satisfacer los requisitos de StyleCop, como:

/// <summary> 
    /// Gets a dto of personal info. 
    /// </summary> 
    /// <param name="userId"> 
    /// The id of the user. 
    /// </param> 
    /// <returns> 
    /// A dto containing personal info. 
    /// </returns> 
    public PersonalInfoDTO GetPersonalInfoDTO(int userId) {...} 

¿Hay una manera estándar de frasear un resumen vs vuelve una descripción? ¿Qué pones en tus descripciones param?

Answer 1

trato de evitar duplicados mediante la descripción del proceso, así como en el resumen. En los parámetros, puede agregar detalles, como rangos válidos, o cómo se espera que el usuario obtenga esta información. Para los retornos que también enumeran las condiciones de error, por ejemplo:

/// <summary> 
/// Gets a dto of personal info by querying the current list of users (or active directory or SQL) 
/// </summary> 
/// <param name="userId"> 
/// The id of the user. Must be greater than 0. The ID is stored in the application context or can be retrieved by a call to GetUserIdByName. 
/// </param> 
/// <returns> 
/// A dto containing personal info. Returns null if the specified user information was not found. 
/// </returns> 
public PersonalInfoDTO GetPersonalInfoDTO(int userId) {...} 

Answer 2

"documentar los métodos que hacen los comentarios realmente útil. Me parece que mis comentarios a menudo contienen una gran cantidad de repetición sólo para satisfacer los requisitos de StyleCop"

útil y redundante no tienen nada que ver entre sí.

No ha definido "útil" en su pregunta. Por lo general, significa "más de lo requerido por stylecop". Si sientes la necesidad de escribir algo más, entonces, escribe algo más. Stylecop es el mínimo; eres libre de ir más allá de esos mínimos.

En su caso, ya que está escribiendo un resumen de una función que hace muy poco. Es muy común que los elementos formales (parámetros y tipos de devolución) y el resumen se repitan entre sí. No estoy seguro de cómo esta repetición falla la prueba "útil". Tal vez si hay algo que falta podría agregarlo. Siéntase libre de expandir y escribir más: nada le impide escribir documentación "útil" que es más que el mínimo.

Redundante, aunque tedioso, no parece ser útil.

Recuerde, sus comentarios terminarán creando índices y páginas de texto plano. Las partes formalmente estructuradas son esenciales para indexar y formatear.

Para clases más complejas (y funciones), el resumen es un lugar para expandir el matiz. Por ejemplo, "¿por qué?" o "cuando se puede y no se puede usar", y "otras restricciones" y "muestras de código" y ese tipo de cosas que serían más útiles.

En cualquier momento, puede --y debería-- escribir más que el mínimo. Sin embargo, para funciones triviales, no tiene sentido escribir más que el mínimo.

Answer 3

Si se ve forzado a ti, entonces es posible que tengas que sufrir con algunas repeticiones, ya que ya usas buenas técnicas de auto-documentación como nombres inteligentes.

Otras cosas bien que se podría incluir en la documentación serían: 1) Formateo - ¿Hay alguna restricción sobre identificación de usuario, como "Todos los usuarios por debajo de 500 son los administradores" o algo por el estilo? Estos son buenos para comentar con el param.

2) Excepciones: si su método va a tirar o pasar uno, documentéelo para que las personas que lo utilicen sepan cómo manejarlo.

3) Ejemplos de código - que muestran cómo utilizar el método

4) Condiciones Especiales - será objeto de retorno estar en cualquier tipo de condición extraña? Si no se encuentra el ID de usuario, ¿devuelve un nulo o un espacio en blanco/error PersonalInfoDTO?

Y por supuesto, en métodos simples parecerá que hay mucha información redundante, pero un código más complejo puede beneficiarse inmensamente de una documentación completa.

Answer 4

Hay una razón para hacer cumplir esta norma, incluso si cree que a veces es información redundante. (es decir, "userId -> la ID del usuario") Este comentario también contiene implícitamente la información de que NO hay restricciones adicionales en ese parámetro.

Así,

... 
///<param name="angle"> 
///The angle in degrees. Must be below 360 and above 0. 
///</param> 
... 

Si no se agrega que "debe estar por debajo y por encima de x y" entonces usted está indicando que no hay ninguna restricción en el parámetro.

mismo modo para la etiqueta < retornos>. Puede pensar que el valor de retorno se explica por sí mismo, pero la etiqueta < returns> es donde debería decirle a la parte llamante si esto podría devolver nulo por error. O si devuelve un solo valor, incluso si hay una lista de posibles respuestas.

Este tipo de información es muy muy importante, y stylecop solo exige que lo agregue.

Answer 5

Tiendo a ser muy suspicaz con las herramientas que te obligan a agregar comentarios en lugares muy arbitrarios.

No me malinterpreten, yo soy un firme defensor de los comentarios. Pero los comentarios como los de su ejemplo son puro "ruido": no agregan nada útil, y cualquier información significativa, si la hay, se oculta detrás de la pelusa.

Si los comentarios pueden ser generados por una herramienta automática ... entonces los humanos no tienen nada que escribir en primer lugar. Si eso es obligatorio por alguna otra razón (generación de documentación externa, por ejemplo), debe tener algún tipo de secuencia de comandos automatizada para generar esos y colocar los resultados en una ubicación discreta.

Por supuesto, hay un montón de cosas significativas que pudieran decir de la interfaz de esta función. ¿Cuáles son los límites en los parámetros, por ejemplo?

Answer 6

Jayrdub:

Tenga en cuenta que el puntode esos comentarios es crear documentación de su código. La redundancia está bien, ya que diferentes porciones de esos comentarios pueden usarse de manera diferente en diferentes escenarios; no todos los comentarios completos se pueden usar en ciertas circunstancias.

Aunque XML doc es útil para crear archivos de ayuda estilo MSDN, también se usa ampliamente en intellisense y tooltips dentro de Visual Studio. Su resumen será visible en ciertos momentos, sus etiquetas de param estarán visibles en otros momentos, y su etiqueta de devoluciones será visible otras veces. A veces todos serán visibles juntos, y a veces no. En resumen, la redundancia es útil. Le proporciona ayuda como programador en diferentes circunstancias cuando usa el método o la clase que documenta.

Answer 7

Hay una gran cantidad de repeticiones - el peor en mi humilde opinión es Propiedades, donde se supone que debes completar el valor <> describiendo la propiedad, pero intellisense solo muestra el resumen <> que para una propiedad solo puede describir el mismo cosa, entonces terminas diciendo lo mismo dos veces.

intento resumir brevemente la propiedad/método en el resumen, pero poner descripciones más detalladas en la < PARAM>, < valor>, y vuelve <> campos para que proporcionen alguna información realmente más útil. (por ejemplo, si se pueden pasar como nulos, etc.)

Lo segundo que hago es usar un complemento que he escrito para autogenerar y actualizar automáticamente) los comentarios del Doc, para minimizar el trabajo involucrado en la documentación del código: si una herramienta automatizada puede completar la mayoría de los detalles para mí, se minimiza el esfuerzo involucrado en el mantenimiento de esta información "duplicada". También auto-formatea y ajusta los comentarios para mantenerlos ordenados.

Consulte http://www.atomineer.com/AtomineerUtils.html para obtener más información y una descarga gratuita.

Answer 8

Puede hacerlo útil:

/// <summary> 
/// Gets the user's personal information. 
/// </summary> 
/// <remarks> 
/// We need this data transfer object in order to bridge Backend.SubsystemA 
/// and Backend.SubsystemB. The standard <see cref="PersonalInfo"/> won't 
/// work. 
/// </remarks> 
/// <param name="userId">Integer representing the user's ID.</param> 
/// <returns> 
/// <see cref="PersonalInfoDTO"/> representing the user, or <c>null</c> 
/// if not available. 
/// </returns> 
public PersonalInfoDTO GetPersonalInfoDTO(int userId) {...} 

Para mí, summary es el alto nivel "¿cuál es el propósito de este método de" información, remarks es para una explicación más detallada, y see es donde se pueden hacer es fácil moverse por su documentación. Cada uno de esos agrega valor.

De hecho, me encantan los comentarios de documentación gracias a ReSharper. He reasignado el comando QuickDoc al CTRL+SHIFT+Q.

Answer 9

Si está haciendo Java, debe tener cuidado con la documentación completa: cuanto más documenta, hay menos posibilidades de que los usuarios encuentren las cosas realmente relevantes. Agregar marcado adicional solo lo empeora.

Es posible que desee considerar la captura de "directivas" o al menos destacarlas con mucha fuerza.

Ver mi respuesta detallada en "tips for writing a great javadoc" que se basan en mi Ph.D. investigación sobre este tema.

Answer 10

Los problemas son los siguientes ....

1. derecho. Nadie te impide escribir un comentario, pero se vuelven más difíciles de mantener. Alguien que lea el código puede confundirse si el comentario no coincide con el código. Admitamos que todos cambiamos el código más tarde y olvidamos/no tenemos tiempo para actualizarlos. ment
2. Algunos métodos son realmente muy simples y no necesitan ningún comentario.
3. Es más difícil leer a través de un código escrito correctamente de 1000 líneas que 100 líneas. Sí, incluso con el coloreado de estudio visual
4. Se necesita mucho tiempo para comentar CADA MÉTODO SIMPLE en su código.
5. Estos comentarios son correctos si está creando una biblioteca pero no para algo no reutilizable ... como una pequeña aplicación Silverlight.