Guía del aspecto: Documentación
El aspecto de documentación responde a una pregunta: ¿está explicado este código para quien tenga que usarlo o cambiarlo? Las métricas no pueden leer los comentarios ni juzgar si dicen la verdad. Lo que sí pueden contar es de tres clases:
- cuánto comentario hay: líneas de comentario y su proporción respecto al código;
- dónde hay documentación de API: qué parte de las clases, los métodos y los campos lleva un comentario
Javadoc (
/** … */); - cuánto trabajo pendiente está apuntado: los marcadores
TODOy similares.
Las tres miran el mismo material (los comentarios), pero contestan cosas distintas. Una clase puede tener un ratio de comentarios alto porque está llena de código comentado y no tener un solo método documentado. Otra puede tener todos sus métodos con Javadoc de una línea y un ratio bajo.
Para quien empieza. Un comentario
//o/* */explica el cómo a quien lee el código. Un comentario/** */delante de una clase o un método es documentación de la API: la herramienta Javadoc lo convierte en las páginas que lee quien usa esa clase sin abrir su código. Las métricas de este aspecto separan los dos.
Por dónde empezar
- «Cobertura Javadoc de métodos» (
Jm): qué parte de los métodos tiene Javadoc. Es la única métrica del aspecto que el catálogo de Stau Metro marca como esencial, y la más útil porque los métodos son lo que otros llaman. No depende del largo de los comentarios, así que se compara bien entre clases y paquetes de tamaño distinto. - «Ratio real de comentarios» (
TCOM_RAT) o «ratio de comentarios» (COM_RAT): cuánto comentario acompaña al código. Sirven para localizar extremos, no para fijar un objetivo. - «Número de comentarios TODO» (
TODO): dónde se acumula el trabajo que alguien apuntó y no hizo. Lo útil es su evolución y leer cada marcador.
Ninguna de las métricas del aspecto tiene umbrales de referencia en Stau Metro, y no se ha encontrado ninguna cifra con respaldo empírico que valga para cualquier proyecto. Se leen por comparación: entre elementos del mismo proyecto y en el tiempo.
Todas las métricas del aspecto
Las ocho las calcula Stau Metro. «Mejor si sube» indica que el plugin les da la dirección «más alto es mejor»; las demás son informativas: ni alto ni bajo es mejor.
| Métrica | Niveles | Qué dice | Dirección |
|---|---|---|---|
«Líneas de comentario» (CLOC) |
método, clase, interfaz, paquete, módulo, proyecto, tipo de fichero | Líneas ocupadas por comentarios, también las que tienen código delante | informativa |
«Líneas de Javadoc» (JLOC) |
método, clase, interfaz, paquete, módulo, proyecto | La parte de CLOC que son comentarios /** */ |
informativa |
«Ratio de comentarios» (COM_RAT) |
método, clase, interfaz, paquete, módulo, proyecto, tipo de fichero | CLOC entre las líneas no vacías del elemento |
informativa |
«Ratio real de comentarios» (TCOM_RAT) |
método, clase, interfaz, paquete, módulo, proyecto | Líneas que solo son comentario entre líneas que tienen código; puede pasar del 100 % | informativa |
«Cobertura Javadoc de clases» (Jc) |
paquete, módulo, proyecto | Qué parte de las clases lleva Javadoc en su declaración | mejor si sube |
«Cobertura Javadoc de métodos» (Jm) |
clase, interfaz, paquete, módulo, proyecto | Qué parte de los métodos lleva Javadoc | mejor si sube |
«Cobertura Javadoc de campos» (Jf) |
clase, interfaz, paquete, módulo, proyecto | Qué parte de los campos y constantes lleva Javadoc | mejor si sube |
«Número de comentarios TODO» (TODO) |
método, clase, interfaz, paquete, módulo, proyecto, tipo de fichero | Marcadores de trabajo pendiente que reconoce el IDE (TODO y FIXME por defecto) |
informativa |
En paquete, cada métrica tiene además una variante recursiva (CLOC(rec), Jm(rec)…) que suma los subpaquetes.
Cuánto comentario frente a dónde hay documentación
Las métricas de volumen (CLOC, JLOC, COM_RAT, TCOM_RAT) y las de cobertura (Jc, Jm, Jf) responden a
preguntas distintas, y conviene elegir antes de mirar.
Volumen: COM_RAT, TCOM_RAT |
Cobertura: Jc, Jm, Jf |
|
|---|---|---|
| Qué cuenta | líneas | elementos con o sin Javadoc |
| Qué comentarios ve | todos: //, /* */, /** */, licencias, código comentado |
solo el /** */ colocado justo delante de la declaración |
| Pregunta | ¿cuánto se explica este código? | ¿dónde falta documentación de API? |
| Valor alto | puede ser buena documentación, código opaco o código comentado | todos los elementos tienen comentario, sea bueno o no |
| Uso típico | encontrar extremos | encontrar huecos en una API |
Elige la cobertura cuando el código lo usan otros: una biblioteca, un módulo que publica servicios, una
interfaz con varias implementaciones. Un Jm bajo en una interfaz pública es un hueco concreto que se arregla
método a método.
Elige el volumen para ver de un vistazo qué zonas del código casi no tienen comentarios o tienen muchísimos, y luego abrirlas. Un ratio muy alto es tan sospechoso como uno muy bajo.
Entre los dos ratios, la diferencia está en las líneas mixtas, como x = 1; // reset. COM_RAT las cuenta a
la vez como comentario y como línea del elemento, y divide por todas las líneas; TCOM_RAT las cuenta solo como
código y divide por las líneas con código. Por eso no viven en la misma escala. Un elemento con 10 líneas no
vacías, 4 de ellas solo de comentario y ninguna mixta, tiene COM_RAT = 4 / 10 = 40 % y TCOM_RAT = 4 / 6 ≈ 67 %.
Si además dos de las seis líneas de código llevan un comentario al final, COM_RAT sube a 6 / 10 = 60 % y
TCOM_RAT no cambia. Cuanto más se separen los dos, más comentario va al final de las líneas.
Ojo. «Ratio de comentarios» no significa lo mismo en todas las herramientas: unas dividen por las líneas de código y otras por el total. Antes de comparar una cifra con la de otra herramienta, mira qué divide cada una (ver la página de «
COM_RAT»).
Cómo se combinan
Con el tamaño, siempre. CLOC y JLOC crecen con el código. Comparar el CLOC de dos clases de tamaño muy
distinto no dice nada; para eso están los ratios, o la lectura junto a las
«líneas de código» (LOC) y las
«líneas sin comentarios» (NCLOC). En método, clase e interfaz,
NCLOC es exactamente el denominador de TCOM_RAT. La «guía de tamaño» explica el resto.
JLOC dentro de CLOC. JLOC es una parte de CLOC. Si casi todo el CLOC de un paquete es JLOC, los
comentarios son documentación de API; si JLOC es una fracción pequeña, son comentarios de implementación,
cabeceras o código comentado. JLOC dice cuánto Javadoc hay; Jm, a cuántos métodos acompaña. Mucho JLOC con un
Jm bajo es documentación concentrada en unas pocas clases.
Coberturas por elemento. Mira Jm primero, Jc después y Jf sobre todo en las constantes públicas. Jm y
Jf cuentan los métodos y los campos de cualquier visibilidad: los métodos privados y los accesores triviales
bajan Jm sin que haga falta documentarlos. Checkstyle, en cambio, solo exige Javadoc por defecto en los métodos
public y no lo pide en los que llevan @Override. Si la pregunta es la API pública, el porcentaje de Stau Metro
mezcla en el denominador métodos que nadie pide documentar; mira el valor de las clases y las interfaces públicas
concretas.
Del método al proyecto. Tres detalles hacen que los valores de distintos niveles no se sumen ni se promedien sin más:
- En clase e interfaz,
CLOC,JLOC,COM_RATyTCOM_RATno incluyen las clases anidadas con nombre, que tienen su propio valor.TODOsí las incluye, así que sumar elTODOde todas las clases cuenta dos veces los marcadores de las anidadas. - En paquete, módulo y proyecto,
CLOC,COM_RAT,TCOM_RATyTODOrecorren ficheros enteros, de cualquier lenguaje, con la cabecera de licencia y lo que quede fuera de las clases;JLOC, solo los ficheros Java. ElCLOCde un paquete puede ser mayor que la suma del de sus clases. - El
Jmde un paquete no es la media delJmde sus clases: cuenta cada método una vez e incluye los de las interfaces.
Las trampas generales de agregar están en «Agregar métricas».
Con el código de test. En paquete, módulo y proyecto entran también los ficheros y las clases de test, y no hay
variante «solo producción» en este aspecto. Los métodos de test casi nunca llevan Javadoc, así que en un módulo con
muchos tests Jm baja aunque la API esté bien documentada. Para separar las dos cosas, mira los paquetes de
producción por su cuenta.
TODO con lo demás. TODO se lee junto a CLOC (qué parte de los comentarios son tareas) y junto a la
«guía de mantenibilidad»: el
«ratio de deuda técnica» estima la deuda a partir de reglas, y
los TODO son la parte que alguien apuntó a mano. Sus mejores lecturas son en
el tiempo, que es terreno de la «evolución del código».
Qué no miden
- Si el comentario es bueno. Ninguna métrica del aspecto lee el texto. Un
/** */vacío cuenta paraJm, y un comentario que repite el nombre del método vale lo mismo que uno que explica un caso límite. Steidl, Hummel y Juergens (2013) lo plantean como punto de partida: los análisis de calidad que solo miran el ratio de comentarios no bastan, porque hay comentarios, como los de licencia o el código comentado, que no ayudan a entender el sistema y deberían quedar fuera. Proponen clasificar los comentarios en siete categorías (de copyright, de cabecera, de miembro, en línea, de sección, código comentado y de tarea) y medir cada una por separado. Las métricas de este aspecto, salvo las de Javadoc yTODO, no hacen esa distinción. - Si el comentario sigue siendo cierto. Un comentario desactualizado engaña más que su ausencia, y cuenta igual. Ninguna métrica estática ve la diferencia entre un comentario y el código que describe.
- El código que se explica solo. Nombres claros, tipos precisos y métodos cortos documentan sin comentarios. Un código así puede tener ratios bajos y ser fácil de leer; uno opaco puede compensar con muchos comentarios. Por eso ningún ratio tiene una dirección «mejor si sube».
- La documentación fuera del código. README, guías, decisiones de arquitectura, el sitio de la API: nada de eso entra en estas métricas.
- La deuda que nadie apuntó.
TODOcuenta marcadores, y solo los patrones que reconoce el IDE con su configuración. Potdar y Shihab (2014) estudiaron la deuda técnica que los propios desarrolladores admiten en los comentarios (self-admitted technical debt) en cuatro proyectos de código abierto: la encontraron en entre el 2,4 % y el 31 % de los ficheros, y solo entre el 26,3 % y el 63,5 % se eliminaba después de introducirse. Un recuento deTODOque crece cuenta esa historia; uno que vale 0 no dice que no haya deuda.
Qué cuenta exactamente cada herramienta, y por qué el ratio de comentarios de dos herramientas no coincide, está en «Herramientas» y en la sección «En las herramientas» de cada página de métrica.
Referencias
- Steidl, D., Hummel, B. y Juergens, E. (2013). «Quality Analysis of Source Code Comments». Proceedings of the 21st International Conference on Program Comprehension (ICPC 2013), 83-92. https://doi.org/10.1109/ICPC.2013.6613836
- Potdar, A. y Shihab, E. (2014). «An Exploratory Study on Self-Admitted Technical Debt». Proceedings of the 30th IEEE International Conference on Software Maintenance and Evolution (ICSME 2014), 91-100. https://doi.org/10.1109/ICSME.2014.31
- 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