Cobertura Javadoc de métodos
| Sigla | Jm (Jm(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 | PercentMethodsJavadocedClass, PercentMethodsJavadocedInterface, PercentMethodsJavadocedPackage, PercentMethodsJavadocedRecursivePackage, PercentMethodsJavadocedModule, PercentMethodsJavadocedProject |
En pocas palabras
Dice qué parte de los métodos tiene un comentario Javadoc. Es la medida de cobertura de documentación más útil porque los métodos son lo que otros programadores llaman: describen qué hacen, qué piden y qué devuelven. En las interfaces, además, sus métodos son el contrato que tienen que cumplir quienes las implementan.
Qué mide
La cobertura de documentación del comportamiento. Por ser un cociente entre elementos documentados y elementos, no depende de cuántas líneas tenga cada comentario, y se puede comparar entre clases, paquetes y proyectos de tamaño distinto. Funciona como una cobertura de tests: dice dónde falta documentación, no si lo escrito es bueno.
Cómo se calcula
Un método está documentado si tiene un comentario de documentación reconocido como tal: debe preceder
inmediatamente a la declaración; los comentarios /** */ dentro de un cuerpo se ignoran (especificación de Javadoc).
No se examina el contenido: un comentario vacío cuenta.
Ejemplo
/** Catalog of products. */
public class Catalog {
private int size;
/** Adds a product. */
public void add(String name) { size++; }
private void grow() { }
public int size() { return size; }
}
Métodos: add, grow y size. El constructor por defecto no está escrito en el código y no cuenta. Solo add tiene
Javadoc: Jm de Catalog = 1 / 3 ≈ 33,3 %. Si solo cuentan los métodos públicos, sería 1 / 2 = 50 %; esta
métrica no los separa.
Cómo interpretarla
Sin umbrales de referencia en Stau Metro. Pautas:
- En paquetes, módulos o proyectos que son una API pública, apunta a un valor alto.
- En código interno, la cobertura plena suele ser un coste sin beneficio: los nombres claros documentan mejor que un comentario por método.
- Los métodos que sobrescriben otros, como
toString, cuentan como no documentados si no llevan su propio comentario. - Los métodos privados y los accesores triviales (
getX,setX) bajan el porcentaje sin que haga falta documentarlos.
Ojo. Mira siempre también el valor sobre elementos concretos. Un 90 % global puede esconder una interfaz pública sin una sola línea documentada.
Para profundizar
Como todo ratio, es manipulable: basta añadir comentarios /** */ vacíos, porque no se examina el contenido. Lo más
informativo suele ser su evolución: si baja cada vez que se añaden métodos públicos, el equipo no los documenta.
Relación con otras métricas
- «Cobertura Javadoc de clases» (
Jc) y de «campos» (Jf): la misma pregunta sobre otros elementos. - «Líneas de Javadoc» (
JLOC): cuánto Javadoc hay, no a cuántos métodos acompaña. - «Número de métodos» (
METH): da el orden de magnitud del denominador a nivel de paquete, módulo y proyecto, pero no coincide con él:METHcuenta también los métodos de clases anónimas y locales. - «Ratio de comentarios» (
COM_RAT): la densidad de comentarios, sea o no de API.
En las herramientas
Stau Metro.
- Clase (
PercentMethodsJavadocedClass): los métodos escritos en el código, constructores incluidos y de cualquier visibilidad, abstractos incluidos. Los que genera el compilador para enumerados yrecordno cuentan. Sin métodos no hay valor, como en un enumerado sin métodos propios. No se calcula para interfaces, tipos de anotación, clases anónimas ni locales; los métodos de estas dos últimas no cuentan para ninguna clase. - Interfaz (
PercentMethodsJavadocedInterface): los métodos declarados en la interfaz (abstractos, por defecto, estáticos y privados), sin los heredados. Los tipos de anotación no tienen valor. - Paquete, módulo y proyecto (
PercentMethodsJavadocedPackage,PercentMethodsJavadocedRecursivePackage,PercentMethodsJavadocedModule,PercentMethodsJavadocedProject): todos los métodos de las clases contadas (las que no son anónimas ni locales, anidadas, interfaces y tipos de anotación incluidos), también las de test. No se cuentan los métodos de clases anónimas ni de clases locales, pero sí los de las clases con nombre que haya dentro de ellas. Por eso el valor agregado no es la media de los valores de clase: incluye los métodos de las interfaces y pondera cada método por igual. El catálogo de Stau Metro la marca como esencial (entra en su perfil de revisión rápida).
Checkstyle (MissingJavadocMethod): comprueba la ausencia de Javadoc en métodos y constructores. Por defecto solo
vigila los de visibilidad public (scope = public) y no exige Javadoc en los métodos marcados con @Override.
Esa es la diferencia con Jm: Checkstyle limita la comprobación a la API visible, y Jm cuenta todos los métodos.
Referencias
- Oracle, especificación de comentarios de documentación de Javadoc (JDK 21): https://docs.oracle.com/en/java/javase/21/docs/specs/javadoc/doc-comment-spec.html
- Checkstyle, comprobación
MissingJavadocMethod: https://checkstyle.sourceforge.io/checks/javadoc/missingjavadocmethod.html