¿Debería un comentario de método incluir tanto un resumen como una descripción de retorno cuando a menudo son tan similares?

10

Soy un defensor del código debidamente documentado, y soy muy consciente de las posibles desventajas del mismo . Eso está fuera del alcance de esta pregunta.

Me gusta seguir la regla de agregar comentarios XML para cada miembro público, considerando cuánto me gusta IntelliSense en Visual Studio.

Sin embargo, hay una forma de redundancia, que incluso a un comentarista excesivo como yo le molesta. Como ejemplo, tome List.Exists () .

/// <summary>
///     Determines whether the List<T> contains elements
///     that match the conditions defined by the specified predicate.
/// </summary>
/// <returns>
///     true if the List<T> contains one or more elements that match the
///     conditions defined by the specified predicate; otherwise, false.
/// </returns>
public bool Exists( Predicate<T> match )
{
    ...
}

Summaryy returnsbásicamente dicen lo mismo. A menudo termino escribiendo el resumen más desde una returnsperspectiva, dejando caer la returnsdocumentación por completo.

Devuelve verdadero cuando la Lista contiene elementos que coinciden con las condiciones definidas por el predicado especificado; de lo contrario, falso.

Además, la documentación de devoluciones no aparece en IntelliSense, por lo que prefiero escribir cualquier información relevante de inmediato summary.

  1. ¿Por qué necesitarías documentar por returnsseparado summary?
  2. ¿Alguna información sobre por qué Microsoft adoptó este estándar?
Steven Jeuris
fuente

Respuestas:

3

Puede inferir una de otra, pero esas dos secciones permanecen separadas, porque ayuda a centrarse en la que le interesa a la persona cuando revisa / usa el código .

Tomando tu ejemplo, preferiría escribir:

/// <summary>
/// Determines whether the List<T> contains elements that match the conditions
/// defined by the specified predicate.
/// </summary>
/// <returns>
/// A value indicating whether at least one element matched the predicate.
/// </returns>
public bool Exists(Predicate<T> match)
{
    ...
}
  • Si estoy revisando este código y quiero saber qué hace el método, leo el resumen, y eso es todo lo que me importa.

  • Ahora, imaginemos que estoy usando su método y el valor de retorno que recibo es extraño, dada la entrada. Ahora, realmente no quiero saber qué hace el método, pero sí quiero saber algo más sobre el valor de retorno. Aquí, la <returns/>sección ayuda, y no necesito leer el resumen.

Nuevamente, en este ejemplo, puede inferir el resumen <returns/>e inferir el valor de retorno esperado del resumen. Pero llevando el mismo argumento al extremo, no hay necesidad de documentar su método en absoluto en este caso: el nombre del método, puesto dentro List<T>, con Predicate<T> matchun único argumento es bastante explícito en sí mismo.

Recuerde, el código fuente se escribe una vez, pero se lee muchas veces . Si puede reducir los impuestos especiales para los lectores posteriores de su código, mientras pasa diez segundos escribiendo una oración adicional en la documentación XML, hágalo.

Arseni Mourzenko
fuente
1
¿Estás llamando a un método y no quieres saber qué hace?
jk.
1
@jk: Está dando a entender que ya lo hizo de antemano. Solo cuando falla, quiere 'enfocarse' en el valor de retorno. +1 para el último párrafo, así es esencialmente como me siento también. Incluso si la documentación declara un hecho obvio como en mi ejemplo, tranquiliza al lector de sus expectativas. Cuando los comentarios se gestionan correctamente, dice: "este método está pensado correctamente y no hace más que lo que se menciona aquí", como en la documentación de msdn.
Steven Jeuris
2

Mi uso:
<summary>describe lo que hace el método (para obtener el <returns>).
<returns>describe el valor de retorno .

Enlaces a MSDN: <summary>.<returns>

Jake Berger
fuente
Gracias por el enlace. Pero en ninguna parte la documentación de summaryestado de msdn describe "lo que hace el método". Voté en contra hasta que se tome el tiempo de actualizar su respuesta para aclarar la diferencia entre lo que dice msdn y lo que formula. ; p
Steven Jeuris
2
Ya sea que MSDN diga algo al respecto o no, esta es realmente una buena guía. En su ejemplo, no tiene que repetir todo el resumen, simplemente puede decir "devuelve truesi el predicado coincidió". Si alguien necesita saber qué constituye una coincidencia, puede leer el resto de la documentación.
Blrfl
@Blrfl: No digo que la directriz esté equivocada. Estoy diciendo que está mal hacer referencia a una fuente, lo que implica que algo está escrito allí cuando no lo está. De ahí el voto negativo. Me gustaría mucho ver esta respuesta editada.
Steven Jeuris
@StevenJeuris: Los enlaces a la documentación de MSDN eran meramente información complementaria. MSDN NO dice: "Cuando tienes un <summary>y un <returns>haz esto". Como dijo Blrfl, esta es solo una guía que uno puede o no querer usar.
Jake Berger el
1
@StevenJeuris: Aunque, debido a la forma en que fue escrito, pude ver cómo alguien puede inferir que vino de MSDN.
Jake Berger el
1

¿Por qué necesitaría documentar las devoluciones por separado del resumen?

Creo que si la parte del resumen es realmente larga y descriptiva, podría ser útil tener una parte separada y breve de devoluciones al final.

Por lo general, escribo solo la <summary>parte en mi propio código, redactando la forma en que dijiste "Devuelve _ ".

Pongo cualquier comentario que una persona que llama debe saber que no es obvio por el nombre del método y los parámetros (y sus nombres). Sin embargo, con suerte, el nombre del método y los parámetros hacen que sea lo suficientemente obvio que el comentario puede ser muy breve.

Philip
fuente
1

Últimamente me ha desgarrado la misma pregunta filosófica y todavía no estoy seguro de cuál es una buena solución. Pero hasta ahora, este ha sido mi enfoque ...

  • La documentación del método solo describe lo que las personas que llaman externas deben saber. No habla sobre cómo se hace este trabajo internamente, pero menciona a) por qué la persona que llama querría llamar a este método, b) cuáles serían los resultados esperados de llamar al método. Si es necesario documentar cómo funciona el método, lo pongo en el cuerpo del código.
  • Si un método tiene suficiente complejidad, entonces la descripción general y una sección separada [retornos] parece estar justificada. No desea que el lector lea la descripción completa e intente inferir cómo interpretar el valor de retorno.
  • Si el método es tan simple que la mejor manera de describir lo que hace es decir algo como "Este método devuelve la dirección de la persona", entonces omito la sección [retornos] ya que agregar parece ir en contra del principio DRY y estoy un gran defensor de eso. Muchos métodos de acceso de una sola línea parecen caer en esta categoría.
DXM
fuente
Sí, puedo conectarme con los puntos mencionados y seguirlos más o menos. El problema es que es una convención bastante subjetiva, que podría ser la razón por la cual Microsoft simplemente optó por agregar siempre returns. También noto que siempre usan la misma formulación, por ejemplo, "verdadero si ...; de lo contrario, falso " para los valores de retorno booleanos. Me pregunto si también han especificado una convención para eso.
Steven Jeuris
0

El resumen debe ser tan descriptivo como pueda ser útil; Las descripciones de los parámetros y el valor de retorno deben ser breves y dulces. Si puede elegir entre una palabra y cinco, use una. Ajustamos tu ejemplo:

verdadero si la Lista contiene uno o más elementos que coinciden con las condiciones definidas por el predicado especificado; de lo contrario, falso.

se convierte

verdadero si algún elemento de la Lista coincide con el predicado; de lo contrario falso.

Caleb
fuente
En realidad, escribirlo así me hizo darme cuenta de la ventaja de la forma estándar de Microsoft de comenzar con "Determina si ..." . Siento que es más legible ya que primero explica lo que está haciendo, antes de decir cuál es el resultado. Eso es un paso menos de indirección. Estoy de acuerdo en que el returnsde Microsoft es demasiado largo. Si debe hacer algo, es simplemente asegurar que verdadero significa que coincide y falso que no.
Steven Jeuris