Cobertura Javadoc de clases
| Sigla | Jc (Jc(rec) en la variante recursiva de paquete) |
| Aspecto | «Documentación» |
| Se mide en | paquete, módulo, proyecto |
| Tipo de valor | proporción entre 0 y 1, que el plugin muestra como porcentaje |
| Dirección | más alto es mejor |
| Stau Metro | PercentClassesJavadocedPackage, PercentClassesJavadocedRecursivePackage, PercentClassesJavadocedModule, PercentClassesJavadocedProject |
En pocas palabras
De todas las clases que hay en un paquete, módulo o proyecto, dice qué parte tiene un comentario Javadoc encima. Un 100 % significa que todas lo tienen; no dice si el comentario es bueno.
Qué mide
La cobertura de documentación a nivel de clase: de cuántas clases se ha escrito, al menos, una descripción formal. Funciona como la cobertura de tests: dice dónde falta, no si lo que hay es de calidad. Un comentario que repite el nombre de la clase cuenta igual que uno excelente.
Cómo se calcula
Entran en el recuento las clases nombradas de los ficheros Java: clases ordinarias y abstractas, interfaces,
enumerados, record, tipos de anotación y clases anidadas. Quedan fuera las clases anónimas, las locales
(declaradas dentro de un método) y los parámetros de tipo; una clase con nombre declarada dentro de una anónima o de
una local sí cuenta. Una clase está «documentada» si tiene un comentario de
documentación; el contenido no se examina.
Un comentario de documentación solo es reconocido como tal cuando precede inmediatamente a la declaración (véase «Líneas de Javadoc»).
Ejemplo
package shop;
/** Catalog of products. */
public class Catalog {
static class Entry {
}
}
enum Status { OPEN, CLOSED }
Clases contadas: Catalog, Catalog.Entry y Status. Solo
Catalog tiene Javadoc: Jc = 1 / 3 ≈ 33,3 %.
Cómo interpretarla
No hay umbrales de referencia en Stau Metro. Una orientación razonable:
- En un paquete, módulo o proyecto que ofrece una API a terceros, apunta a un valor alto: las clases son lo primero que busca quien usa la biblioteca.
- En una aplicación cerrada, un valor bajo es una decisión de equipo y no un defecto en sí. Lo que importa es si la documentación que falta es la que hace falta.
- Las clases anidadas y los enumerados pequeños cuentan igual que las grandes, y suelen bajar el porcentaje.
Ojo. La cobertura cuenta clases de cualquier visibilidad, no solo las públicas. Un paquete con muchas clases internas sin documentar puede salir mal parado aunque su API pública esté completa.
Relación con otras métricas
- «Cobertura Javadoc de métodos» (
Jm) y de «campos» (Jf): la misma pregunta sobre otros miembros. - «Líneas de Javadoc» (
JLOC): cuánto texto, no cuántos elementos. - «Número de clases» (
C): da el orden de magnitud del denominador, pero no coincide con él:Ccuenta también las clases anónimas y las locales.
En las herramientas
Stau Metro. PercentClassesJavadocedPackage, PercentClassesJavadocedModule y
PercentClassesJavadocedProject. La variante recursiva de paquete (PercentClassesJavadocedRecursivePackage)
incluye las clases de los subpaquetes. Solo se miran ficheros Java.
- Un paquete o proyecto solo tiene fila si cuenta alguna clase; un módulo tiene fila por cada fichero Java, de modo que un módulo sin clases cuenta 0 de 0 y no tiene valor.
- Entran también las clases de los ficheros de test que estén en el ámbito.
- No existe a nivel de clase o de interfaz: una clase no se cubre a sí misma.