Ratio de comentarios
| 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
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
- «Líneas de comentario» (
CLOC): el numerador. - «Ratio real de comentarios» (
TCOM_RAT): variante más estricta que separa comentario puro y código. - «Líneas de código» (
LOC): las líneas no vacías, el denominador. - «Cobertura Javadoc de métodos» (
Jm): mide si hay documentación en un sitio concreto, no cuánta.
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.CommentRatioRecursivePackageincluye 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
- SonarQube, definición de métricas: https://docs.sonarsource.com/sonarqube-server/latest/user-guide/code-metrics/metrics-definition/
- SciTools, Understand Metrics (manual en PDF), entrada
RatioCommentToCode: https://docs.scitools.com/pdf/metrics.pdf