¿Es necesario un resumen en el método de prueba unitaria?

Question

Dado que la denominación de un método de prueba unitaria hace que su propósito sea más significativo, ¿es necesario agregar un resumen a un método de prueba unitaria?

Ejemplo:

/// <summary>
/// Check the FormatException should be thrown when a give country data line contains a invalid number.
/// </summary>
[TestMethod]
public void FormatException_Should_Thrown_When_Parse_CountryLine_Containing_InvalidNumber()
{
  ...
}

Answer 1

Creo que el nombre descriptivo largo es más importante que el comentario XML. Dado que la prueba unitaria no formará parte de una API, no necesita el comentario XML.

Por ejemplo:

[TestMethod]
public void FormatException_Should_Thrown_When_Parse_CountryLine_Containing_InvalidNumber()
{
  ...
}

es más útil que:

///<summary>
/// Exception Should Thrown When Parse CountryLine Containing InvalidNumber
///</summary>
[TestMethod]
public void Test42()
{
  ...
}

Los comentarios XML deben usarse para documentar API y marcos.

Answer 2

En realidad prefiero usar el atributo de descripción sobre una etiqueta de resumen. La razón es que el valor del atributo Descripción se mostrará en un archivo de resultados. Hace que las fallas sean más fáciles de entender cuando solo está mirando un archivo de registro

[TestMethod,Description("Ensure feature X doesn't regress Y")]
public void TestFeatureX42() {
  ..
}

Answer 3

Personalmente, trato de hacer las pruebas lo suficientemente fáciles como para leer que la documentación sería redundante. Utilizo comentarios en línea dentro del método de prueba para explicar por qué estoy haciendo algo de una manera particular, no qué estoy haciendo.

Answer 4

No es necesario, pero si cree que los comentarios XML agregan valor más allá del nombre de la prueba de la unidad en sí (que parece ser exhaustiva), entonces estará prestando un servicio a otros desarrolladores.

Si el resumen es esencialmente un duplicado directo del nombre del método de prueba unitaria, entonces creo que esto es excesivo.

Answer 5

Para el ejemplo anterior, diría que no es necesario, a menos que use una herramienta que extraiga documentación de la fuente (como javadoc o algo así).

Una regla de oro común es que el código dice lo que estás haciendo y el comentario dice por qué, pero como el nombre es muy detallado (lo cual creo que está bien, ya que nadie tiene que escribirlo) no lo hago. No piense que el comentario aporta algo.

Answer 6

Es necesario agregar un resumen cuando el resumen puede proporcionar más información que puede / debe codificarse en el nombre del método. Tenga en cuenta que cuando digo "necesario" cuando me refiero a cualquier documentación, quiero decir que es "necesario transmitir el 100% del contexto / detalle / matices necesarios a un nuevo codificador que herede el proyecto o a usted mismo 5 años después".

Answer 7

Un comentario XML es totalmente innecesario si tiene un nombre de método descriptivo. Y es imprescindible para los métodos de prueba unitaria.

Ya estás en el camino correcto con un nombre de método de prueba descriptivo. (Muchos profesionales ágiles y TDD creen que un método de prueba debe incluir "debería", por ejemplo, como se muestra en texto del enlace esta publicación de blog.

Personalmente, me gustan los nombres de métodos como este:

MyClass_OnInvalidInput_ShouldThrowFormatException()

Pero esa es simplemente mi preferencia personal.

Answer 8

Si crees que es el mejor uso de tu tiempo, hazlo, de lo contrario no lo hagas. No lo haría.