¿Deben las pruebas de JUnit ser javadocced?

Question

Tengo varios casos de prueba de JUnit que actualmente no están documentados con los comentarios de Javadoc.

El resto de mi código está documentado, pero me pregunto si vale la pena el esfuerzo de documentar estas pruebas.

Answer 1

Si el propósito de la prueba es obvio, no me molesto en documentarlo.

Si no es obvio porque se trata de una situación oscura, o si quiero referirme a un error específico, por ejemplo, en ese caso, agregaré documentación. Sin embargo, no documento excepciones, etc., solo un breve resumen del método. Esto sucede relativamente rara vez. Es más probable que agregue documentación para los métodos de ayuda utilizados en varias pruebas.

Answer 2

No encuentro ningún valor en javadocing los casos de prueba. Acabo de hacer el nombre del método lo suficientemente descriptivo como para saber el propósito de la prueba.

En Ruby, sé que hay herramientas para crear un documento a partir del nombre de las pruebas, pero no he visto una de estas en Java.

Answer 3

Ya sea javadoc o no, creo que las pruebas unitarias deberían documentarse definitivamente. En los casos en que no existe una especificación formal, las pruebas unitarias son lo que más se acerca a la definición del comportamiento esperado del código. Al documentar los casos de prueba, dejará en claro al lector lo que la prueba está probando y por qué lo está probando.

Answer 4

Al pensar en las pruebas como una documentación, no tiene mucho sentido "documentar la documentación". El nombre de cada prueba ya debe describir en sí mismo cuál es el propósito de las pruebas, cuál es el comportamiento que está especificando esa prueba.

Use nombres largos y descriptivos para las pruebas, y mantenga el código de prueba lo más legible posible.

Por ejemplo, eche un vistazo a los casos de prueba en este proyecto . ¿Alguno de ellos hace algo que no sea tan obvio al mirar el nombre de las pruebas y el código de la prueba?

Solo en algunos casos raros, cuando el código de prueba es oscuro, se necesitan comentarios en las pruebas. Por ejemplo, si está probando un código de múltiples subprocesos y el código de prueba hace cosas extrañas para asegurarse de que el código de prueba se ejecute en el orden correcto. Pero incluso en esos casos, un comentario es una disculpa por no escribir un código de prueba más limpio.

Answer 5

No veo por qué debería tratar los casos de prueba de manera diferente a su código de producción con respecto a los comentarios.

Answer 6

Creo que es valioso javadoc las condiciones bajo las cuales pasan las pruebas.

Answer 7

¿Es una herejía sugerir que los comentarios de código son un antipatrón? Estoy de acuerdo con las respuestas anteriores, lo ideal sería que su código fuera lo suficientemente descriptivo como para no tener comentarios. Esto es especialmente cierto si se encuentra en un entorno (empresarial) donde las personas tienden a actualizar el código sin actualizar los comentarios, por lo que los comentarios se vuelven engañosos.

Answer 8

infierno sí. incluso si es justo ...

crear orden, editar orden, guardar, cargar & amp; compruébalo.

si es una prueba realmente simple, entonces tal vez no.

Encuentro que a medida que cambia el código, a veces el motivo de la prueba no es tan obvio como lo era antes.

Answer 9

Tal vez podría conseguir que alguien que no esté completamente familiarizado con su código le brinde una respuesta rápida sobre si sus pruebas se entienden fácilmente como son.

En la empresa para la que trabajo, tratamos de darles a nuestros exámenes nombres descriptivos y complejidad de documentos, pero a menudo es difícil hacer que esto sea correcto. con el primer borrador porque las cosas que son obvias para el desarrollador no siempre son obvias para los demás.

Las pruebas se tratan como código y se envían como parte de un proceso de revisión por pares para que nuestro (pequeño) equipo pueda comentar si una prueba se entiende o no fácilmente.

Si una prueba es un poco confusa, podemos actualizar el nombre o la documentación en consecuencia y obtendremos un mejor indicador de lo que funciona y lo que no.