Ratio real de comentarios

Actualizado el 15 de noviembre de 2026

Sigla TCOM_RAT (TCOM_RAT(rec) en la variante recursiva de paquete)
Aspecto «Documentación»
Se mide en método, clase, interfaz, paquete, módulo, proyecto
Tipo de valor proporción que el plugin muestra como porcentaje; puede superar el 100 %
Dirección informativa: ni alto ni bajo es mejor
Origen no hay una definición original única
Stau Metro TrueCommentRatioMethod, TrueCommentRatioClass, TrueCommentRatioInterface, TrueCommentRatioPackage, TrueCommentRatioRecursivePackage, TrueCommentRatioModule, TrueCommentRatioProject

En pocas palabras

Separa cada línea en una de dos cajas: «solo comentario» o «tiene código». El ratio real es el número de líneas de la primera caja dividido por el de la segunda. Una línea como x = 1; // reset cuenta como código y nada más, de modo que los comentarios al final de línea no inflan la cifra.

Qué mide

La cantidad de comentario independiente por cada línea de código. Es la alternativa estricta al «ratio de comentarios»: este cuenta una línea mixta como comentario y como código a la vez; el ratio real la cuenta solo como código. Un comentario independiente, en su propia línea, suele ser una explicación deliberada; uno al final de línea suele ser una anotación breve.

Cómo se calcula

Se clasifican las líneas no vacías del elemento:

  • línea de comentario puro: solo contiene comentario (y espacio en blanco). Una línea con varios comentarios cuenta una vez;
  • línea con código: cualquier otra, aunque lleve un comentario al final.
TCOM_RAT=lıˊneas de comentario purolıˊneas con coˊdigo\text{TCOM\_RAT} = \frac{\text{líneas de comentario puro}}{\text{líneas con código}}

Como el denominador no incluye los comentarios puros, el resultado puede pasar del 100 %: un elemento con más líneas de comentario que de código da más de 1.

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. Son comentario puro las 6 del Javadoc y // no discount below 100: 7. return price; // unchanged tiene código, así que es código. Quedan 13 − 7 = 6 líneas con código. TCOM_RAT = 7 / 6 ≈ 116,7 %.

Clase Pricing: 15 líneas, 7 de comentario puro y 8 con código: 7 / 8 = 87,5 %.

Para el mismo método, el «ratio de comentarios» da 8 / 13 ≈ 61,5 %. Las dos cifras responden a preguntas distintas: qué parte del texto es comentario, y cuánto comentario hay por línea de código.

Cómo interpretarla

No hay umbrales de referencia. Lee el valor así:

  • Cerca de 0: casi no hay comentarios independientes; quizá solo anotaciones finales.
  • Alrededor de 1: más o menos una línea de comentario por línea de código. En un método pequeño con Javadoc completo es normal, como el ejemplo; en un método largo de lógica sería raro.
  • Muy alto en una clase o paquete: documentación abundante o bloques grandes de código comentado.

Compáralo con el ratio de comentarios: la diferencia entre los dos indica cuánto comentario va en líneas mixtas.

Para profundizar

Al no estar acotado por 1, no es una «proporción» en sentido estricto, sino una razón. Por eso no puede interpretarse como «porcentaje de líneas comentadas»; para eso sirve COM_RAT.

Las cabeceras de licencia largas pesan mucho en ficheros pequeños, y en paquete, módulo y proyecto cuentan como comentario puro.

Relación con otras métricas

En las herramientas

Stau Metro. Numerador: líneas que solo tienen comentario. Denominador: líneas no vacías menos esas. Si no hay líneas con código no hay valor.

  • Método (TrueCommentRatioMethod): sobre el texto del método, incluidas lambdas y clases anónimas o locales.
  • Clase (TrueCommentRatioClass) e interfaz (TrueCommentRatioInterface): sobre el texto de la clase sin sus clases anidadas con nombre, que tienen su propio valor.
  • Paquete (TrueCommentRatioPackage), módulo (TrueCommentRatioModule) y proyecto (TrueCommentRatioProject): sobre todos los ficheros del ámbito, de cualquier lenguaje y también los de test. TrueCommentRatioRecursivePackage incluye los subpaquetes. Los ficheros de texto plano entran con todas sus líneas como «líneas con código», aunque NCLOC los deja fuera.

No existe a nivel de tipo de fichero.

No se ha encontrado documentación de otra herramienta que defina una métrica con esta fórmula.