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

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?

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.

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>

¿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.

Ú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.

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.