Ratio de comentarios

Actualizado el 15 de noviembre de 2026

Sigla COM_RAT (COM_RAT(rec) en la variante recursiva de paquete)
Aspecto «Documentación»
Se mide en método, clase, interfaz, paquete, módulo, proyecto, tipo de fichero
Tipo de valor proporción, casi siempre entre 0 y 1, que el plugin muestra como porcentaje
Dirección informativa: ni alto ni bajo es mejor
Origen no hay una definición original única; la fórmula varía entre herramientas
Stau Metro CommentRatioMethod, CommentRatioClass, CommentRatioInterface, CommentRatioPackage, CommentRatioRecursivePackage, CommentRatioModule, CommentRatioProject, CommentRatioFileType

En pocas palabras

Dice qué parte de un elemento es comentario. Si un método tiene diez líneas y tres tienen comentario, el ratio es 30 %. Sirve para comparar elementos de distinto tamaño sin abrirlos, pero ni el 5 % ni el 50 % son buenos o malos por sí mismos.

Qué mide

La densidad de comentarios: cuánto texto de comentario acompaña a cada línea de un elemento. Es la versión normalizada de las «líneas de comentario», que depende del tamaño.

Sirve para localizar extremos. Un ratio cercano a 0 en una clase grande y pública puede indicar falta de documentación; uno muy alto puede indicar código tan opaco que necesita explicación constante, o código viejo comentado en lugar de borrado.

Cómo se calcula

COM_RAT=CLOClıˊneas no vacıˊas del elemento\text{COM\_RAT} = \frac{\text{CLOC}}{\text{líneas no vacías del elemento}}

Numerador: «CLOC», las líneas ocupadas por comentarios. Denominador: todas las líneas no vacías del elemento, comentarios incluidos. Una línea con código y un comentario al final cuenta en el numerador y en el denominador. Con esta definición el ratio no pasa de 100 % en la práctica: solo una línea con varios comentarios, que cuentan por separado en CLOC, puede hacer que el numerador supere al denominador.

Ojo. Otras herramientas usan denominadores distintos (solo las líneas de código, o líneas más comentarios). Dos «ratios de comentarios» no se pueden comparar sin saber qué divide cada una (véase «En las herramientas»).

Ejemplo

class Pricing {
    /**
     * Applies the discount.
     *
     * @param price the base price
     * @return the final price
     */
    double apply(double price) {
        // no discount below 100
        if (price < 100) {
            return price; // unchanged
        }
        return price * 0.9;
    }
}

Método apply: 13 líneas no vacías (6 del Javadoc y 7 de código, incluidas las dos con un comentario aparte o al final) y CLOC = 8 (6 de Javadoc, // no discount below 100 y // unchanged). COM_RAT = 8 / 13 ≈ 61,5 %.

Clase Pricing: 15 líneas (las 13 anteriores más class Pricing { y la llave final) y CLOC = 8. COM_RAT = 8 / 15 ≈ 53,3 %.

Cómo interpretarla

No hay umbrales de referencia en Stau Metro, ni tampoco una cifra con respaldo empírico que valga para todos los proyectos. Pautas de lectura:

  • Un ratio muy bajo en elementos que forman parte de una API pública sugiere falta de documentación.
  • Un ratio muy alto sugiere código difícil de seguir o código comentado.
  • Un método de pocas líneas con un Javadoc completo tiene un ratio alto sin que eso sea un problema, como en el ejemplo. En métodos pequeños el ratio varía mucho; fíjate más en clases, paquetes y módulos.
  • Compara con el resto del proyecto: la cifra útil es la desviación respecto a la norma de tu código, no un porcentaje absoluto.

Si quieres una versión que no cuente doble las líneas que mezclan código y comentario, mira el «ratio real de comentarios».

Para profundizar

Como el numerador y el denominador comparten las líneas con código y comentario, el ratio tiende a sobrestimar la documentación en código con muchos comentarios finales (x = 1; // reset). Para medir las líneas que solo son comentario hay que separarlas, que es lo que hace TCOM_RAT.

El ratio también es muy sensible a las cabeceras de licencia: en un fichero pequeño, veinte líneas de licencia inflan el valor del fichero, del paquete y del tipo de fichero. En clases y métodos no, porque la cabecera queda fuera de la clase.

Relación con otras métricas

En las herramientas

Stau Metro. Un ratio por nivel, con el numerador y el denominador de cada uno:

  • Método (CommentRatioMethod): comentarios dentro del método entre líneas no vacías del método (con las de lambdas y clases anónimas o locales que contenga).
  • Clase (CommentRatioClass) e interfaz (CommentRatioInterface): comentarios de la clase entre sus líneas no vacías, descontando en ambos las clases o interfaces anidadas con nombre. Los tipos de anotación no tienen valor.
  • Paquete (CommentRatioPackage), módulo (CommentRatioModule), proyecto (CommentRatioProject) y tipo de fichero (CommentRatioFileType): suma de los comentarios de todos los ficheros entre la suma de sus líneas no vacías, de cualquier lenguaje. Para un conjunto sin líneas no hay valor. CommentRatioRecursivePackage incluye los subpaquetes. Entran también los ficheros de test.

SonarQube (comment_lines_density): comment_lines / (lines + comment_lines) * 100. Su recuento de comentarios excluye los no significativos y las cabeceras de Java.

Understand (RatioCommentToCode): líneas de comentario entre líneas de código. Su documentación advierte que, como hay líneas que son a la vez código y comentario, el valor puede superar 1 con facilidad.

Como el denominador de Stau Metro incluye también las líneas que son solo comentario, su valor no es mayor que el de una definición «comentarios entre líneas de código» aplicada al mismo código.

Referencias