Cobertura Javadoc de métodos

Actualizado el 15 de noviembre de 2026

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

Jm=meˊtodos con comentario /∗∗⋯∗/meˊtodos contados\text{Jm} = \frac{\text{métodos con comentario } /** \dots */}{\text{métodos contados}}

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

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 y record no 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