Ratio real de comentarios
| 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.
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
- «Ratio de comentarios» (
COM_RAT): la versión simple, que cuenta doble las líneas mixtas y divide por todas las líneas, así que casi nunca pasa de 100 %. - «Líneas de comentario» (
CLOC): cuenta todas las líneas con comentario, mixtas incluidas. - «Líneas de código sin comentarios» (
NCLOC): las líneas que no son comentario puro. En método, clase e interfaz, el denominador de esta métrica es exactamenteNCLOC.
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.TrueCommentRatioRecursivePackageincluye los subpaquetes. Los ficheros de texto plano entran con todas sus líneas como «líneas con código», aunqueNCLOClos 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.