τTau SolutionsAspectos de calidad

Guía del aspecto: Documentación

Actualizado el 15 de noviembre de 2026

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 TODO y 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

  1. «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.
  2. «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.
  3. «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_RAT y TCOM_RAT no incluyen las clases anidadas con nombre, que tienen su propio valor. TODO sí las incluye, así que sumar el TODO de todas las clases cuenta dos veces los marcadores de las anidadas.
  • En paquete, módulo y proyecto, CLOC, COM_RAT, TCOM_RAT y TODO recorren ficheros enteros, de cualquier lenguaje, con la cabecera de licencia y lo que quede fuera de las clases; JLOC, solo los ficheros Java. El CLOC de un paquete puede ser mayor que la suma del de sus clases.
  • El Jm de un paquete no es la media del Jm de 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 para Jm, 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 y TODO, 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ó. TODO cuenta 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 de TODO que 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