Escribir comentarios de documentación de Java para casos de prueba unitaria

En mi opinión, los casos de prueba de la unidad en sí sirven como documentación para el código. Mi empresa quiere que escriba comentarios detallados de java doc sobre los casos de prueba de unidad. ¿Es necesario hacerlo? ¿Escribes comentarios como ese?

unit-testing documentation

— Vinoth Kumar CM
fuente

suponiendo que el código de prueba esté bien escrito y sea legible, el valor principal de un comentario de este tipo en el código de prueba es como una declaración de intenciones. Eso puede ser muy valioso para los revisores de código, incluso usted mismo en un tiempo, ya que le permite juzgar el código que se escribió es hacer lo que se supone que debe hacer o probar lo que se supone que debe probar. En segundo lugar, puede usar sistemas como JAVADOC o incluso un simple script para raspar los nombres de las pruebas y los comentarios del código para crear un poco de documentación sobre las pruebas que tiene y lo que están haciendo.

— Chuck van der Linden

Respuestas:

Lo que hago es JAVADOC-comment:

la clase, que indica qué clase se prueba por unidad (aunque debería ser obvio ya que la mejor práctica sobre ese tema sugiere que el nombre del caso de prueba debería ser el nombre de la clase + "Prueba" o + "TestCase"). Esto se hace utilizando el comentario de {@link XXXClass} JAVADOC
los métodos, que indican qué método se prueba ({@link XXXClass # method1}). A veces necesito tener múltiples métodos de prueba para un método de una clase para probar adecuadamente todas las rutas. Cuando sucede, escribo una línea adicional que indica qué ruta estoy probando dentro (pero nunca me desvío de mi convención de una línea)

Aparte de eso, no hay otro comentario. Para llamar su atención en otro lugar, tal vez podría usar algo como Cobertura para generar gráficos bonitos de cobertura de código y hacerlos felices de esa manera :-)

Nota adicional: me estoy refiriendo a los casos de prueba de unidad, si estamos hablando de casos de prueba de integración, entonces una o dos líneas más para explicar lo que está sucediendo pueden ser necesarias ...

— Jalayn
fuente

Los requisitos de documentación para cualquier código están completamente cubiertos en las respuestas a esta pregunta: mi jefe quiere una explicación narrada en línea línea por línea de nuestro código

Como resumen de las respuestas que verá allí, "Depende de su situación". Hay casos en los que es razonable (y alentado), y otros en los que es una pérdida de tiempo.

— blueberryfields
fuente

Los comentarios Javadoc se pueden extraer y formatear en un documento de referencia separado, las pruebas unitarias no. Además, tenga en cuenta que lo que escribe en palabras puede ser diferente del código real, y generalmente está describiendo en palabras el comportamiento real esperado. Una de las formas de encontrar errores es comparar la documentación con el código real, si no coinciden, es un error (en cualquiera de ellos y, a veces, en ambos).

La prueba unitaria es para pruebas, no para documentación. Usar la prueba unitaria como documentación es incorrecta y no debe hacerse.

— littleadv
fuente

Encuentro un buen conjunto de pruebas unitarias inmensamente útiles para documentar código. Proporcionan una implementación de referencia sobre cómo se debe usar el código de alguien , junto con la prueba de que el código se comporta correctamente cuando se usa de esa manera.

— Bill Michell

@Bill: no hay discusión sobre eso, es útil. No reemplaza la documentación adecuada.

— littleadv

Depende de la audiencia para su documentación, pero en algunos casos definitivamente tiene razón.

— Bill Michell

Idealmente , las pruebas unitarias no deberían ser la única documentación de un sistema, pero en el mundo real, 9 de cada 10 proyectos están trabajando con código heredado en el que se puede considerar afortunado tener alguna documentación. Y en este caso, prefiero un buen conjunto de pruebas unitarias de ejecución y aprobación sobre un montón de documentos que pueden estar totalmente fuera de sincronización con el código real. (Sí, incluso el Javadoc puede.)

— Péter Török

@ PéterTörök Sí ... Me mudé entre varios empleadores diferentes, algunas compañías muy conocidas. Mucho código heredado. La única unidad de prueba nunca - los que escribieron. Tuviste mucha, mucha suerte. No asumas que lo que viste es lo que sucede en todas partes. E incluso si tiene un conjunto de pruebas unitarias ... ¿Quién dijo que son correctas? ¿Quién dijo que cubren lo que deberían? ¿Quién dijo que los resultados esperados son lo que son? ¿Por qué supone que las pruebas unitarias no están fuera de sincronización? ¿Solo porque "pasan"? Disparates.

— littleadv