Líneas de Javadoc
| Sigla | JLOC (JLOC(rec) en la variante recursiva de paquete) |
| Aspecto | «Documentación» |
| Se mide en | método, clase, interfaz, paquete, módulo, proyecto |
| Tipo de valor | recuento (entero, mínimo 0) |
| Dirección | informativa: ni alto ni bajo es mejor |
| Stau Metro | JavadocLinesOfCodeMethod, JavadocLinesOfCodeClass, JavadocLinesOfCodeInterface, JavadocLinesOfCodePackage, JavadocLinesOfCodeRecursivePackage, JavadocLinesOfCodeModule, JavadocLinesOfCodeProject |
En pocas palabras
Cuenta las líneas de los comentarios que empiezan por /**, los que la herramienta Javadoc convierte en
documentación de la API. Es la parte de los comentarios que es documentación formal, frente a los comentarios ordinarios
(// y /* */).
Qué mide
Cuánto texto de documentación de API tiene un elemento. Aísla de las «líneas de comentario» la parte que va destinada a quien usa el código sin leerlo, y deja fuera las notas para quien lo mantiene.
Según la especificación de la herramienta, los comentarios de documentación se reconocen solo cuando están inmediatamente antes de la declaración de un módulo, paquete, clase, interfaz, constructor, método, miembro de enumerado o campo; los que están dentro del cuerpo de un método se ignoran.
Cómo se calcula
Se suma, para cada comentario de documentación del elemento, el número de líneas de texto fuente no vacías que ocupa
(las reglas de línea son las de «CLOC»). Los comentarios ordinarios no cuentan.
Ejemplo
interface Shape {
/** Area. */
double area();
/**
* Perimeter of the shape.
*/
double perimeter();
// implementors must be immutable
}
/** Area. */ ocupa 1 línea; el segundo comentario, 3. JLOC de Shape = 4. El comentario // no cuenta aquí,
pero sí en CLOC, que valdría 5. Para el método area, JLOC = 1.
Cómo interpretarla
Sin umbrales: es informativa. Compárala con CLOC: la proporción JLOC / CLOC dice cuánto del comentario es
documentación de API. Un valor 0 en un elemento que forma parte de la API pública merece una mirada; para saber qué
parte de los elementos está documentada usa las métricas de cobertura
(«clases», «métodos», «campos»),
que no se ven afectadas por el tamaño de cada comentario.
Ojo. Muchas líneas de Javadoc no equivalen a una API bien documentada: un comentario puede repetir la firma.
Relación con otras métricas
- «Líneas de comentario» (
CLOC): el total del queJLOCes una parte. - «Cobertura Javadoc de clases» (
Jc), de «métodos» (Jm) y de «campos» (Jf): cuántos elementos tienen Javadoc, en vez de cuántas líneas.
En las herramientas
Stau Metro.
- Método (
JavadocLinesOfCodeMethod): el Javadoc del propio método (también de métodos abstractos: un método abstracto con/** Area. */vale 1) más el que haya dentro de su texto, como el de los métodos de una clase anónima. - Clase (
JavadocLinesOfCodeClass) e interfaz (JavadocLinesOfCodeInterface): el Javadoc de la clase, el de sus miembros y el de las clases anónimas o locales que contenga, sin el de las clases o interfaces anidadas con nombre. Los tipos de anotación no tienen valor ni de clase ni de interfaz. - Paquete (
JavadocLinesOfCodePackage), módulo (JavadocLinesOfCodeModule) y proyecto (JavadocLinesOfCodeProject): todos los comentarios de documentación de los ficheros Java del ámbito, también los de test, los depackage-info.javay los que queden fuera de toda clase. Esas mismas líneas cuentan también en elCLOCdel paquete.JavadocLinesOfCodeRecursivePackageincluye los subpaquetes.
Solo se cuentan los ficheros Java; no hay valor para el tipo de fichero.
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