Cobertura Javadoc de campos
| Sigla | Jf (Jf(rec) en la variante recursiva de paquete) |
| Aspecto | «Documentación» |
| Se mide en | clase, interfaz, 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 | PercentFieldsJavadocedClass, PercentFieldsJavadocedInterface, PercentFieldsJavadocedPackage, PercentFieldsJavadocedRecursivePackage, PercentFieldsJavadocedModule, PercentFieldsJavadocedProject |
En pocas palabras
Qué parte de los campos (las variables de una clase, las constantes de una interfaz) tiene un comentario Javadoc. Importa sobre todo en los campos que forman parte de la API: constantes públicas y campos visibles desde fuera.
Qué mide
La cobertura de documentación del estado de un elemento. En la mayoría de las clases bien encapsuladas los campos son privados y no hacen falta comentarios de documentación; en las que exponen constantes o campos públicos, la documentación de cada uno es el contrato.
Cómo se calcula
En una clase se cuentan los campos que están escritos en el código, de cualquier visibilidad. Los campos implícitos de
las componentes de un record no se cuentan, porque no pueden llevar Javadoc. En una interfaz se cuentan sus
constantes, que en Java son siempre públicas.
Ejemplo
public class Catalog {
/** Maximum entries. */
static final int MAX = 100;
private int size;
// ...
}
Dos campos, uno con Javadoc: Jf de Catalog = 1 / 2 = 50 %. size es privado y quizá no necesite
documentación, pero cuenta igual: la cobertura no distingue visibilidades.
Cómo interpretarla
Sin umbrales de referencia. Un valor alto es mejor por definición de la métrica, pero en la práctica:
- en una interfaz con constantes públicas, apunta a un valor alto;
- en una clase de dominio con campos privados, un valor bajo es normal;
- un elemento sin campos no tiene valor, que no es lo mismo que 0 %.
Relación con otras métricas
- «Cobertura Javadoc de clases» (
Jc) y de «métodos» (Jm): la misma pregunta sobre otros miembros. - «Líneas de Javadoc» (
JLOC): cuánto texto de Javadoc, no cuántos campos.
En las herramientas
Stau Metro.
- Clase (
PercentFieldsJavadocedClass): los campos escritos en la clase, de cualquier visibilidad, incluidas las constantes de un enumerado y sin los implícitos de unrecord. No hay valor si la clase no tiene campos. No se calcula para clases anónimas ni locales (sus campos no cuentan para ninguna clase), ni para tipos de anotación. - Interfaz (
PercentFieldsJavadocedInterface): las constantes de la interfaz. El código excluye lasprivate, que el lenguaje no permite en una interfaz, así que en la práctica entran todas. Los tipos de anotación no tienen valor. - Paquete, módulo y proyecto (
PercentFieldsJavadocedPackage,PercentFieldsJavadocedRecursivePackage,PercentFieldsJavadocedModule,PercentFieldsJavadocedProject): los campos de todas las clases contadas (las que no son anónimas ni locales, anidadas, interfaces y tipos de anotación incluidos), también las de test. Los campos de las clases anónimas o locales no cuentan. Un módulo sin campos no tiene valor.