Cómo leer una métrica: niveles, tipos de valor, dirección y umbrales
Cada página de métrica empieza con una ficha. Esta página explica qué quiere decir cada fila y cómo se lee un valor: en qué elemento se mide, qué clase de número es, si conviene que sea alto o bajo y a partir de dónde se avisa.
La ficha de una página
Esta es la ficha de la «complejidad ciclomática»:
| Sigla | v(G) |
| Aspecto | «Complejidad» |
| Se mide en | método |
| Tipo de valor | recuento (entero, mínimo 1) |
| Dirección | más alto es peor |
| Umbrales de referencia | aviso por encima de 10, error por encima de 20 (Stau Metro) |
| Origen | Thomas J. McCabe, 1976 |
| Familia | «Métricas de McCabe» |
| Stau Metro | CyclomaticComplexity |
- Sigla: la abreviatura con que aparece en la literatura y en las herramientas. No se traduce.
- Aspecto: el «aspecto de calidad» al que pertenece, con enlace a su guía.
- Se mide en: los niveles, explicados abajo.
- Tipo de valor: qué clase de número es y su rango.
- Dirección: si un valor alto es malo, bueno o ninguna de las dos cosas.
- Umbrales de referencia: a partir de qué valor se avisa, y de dónde sale ese valor. Si no hay umbrales con procedencia, la fila no aparece.
- Origen y Familia: quién la propuso y en qué conjunto clásico se publicó, si se conoce.
- Stau Metro: los ids de métrica del plugin, uno por nivel o variante, o «no la calcula».
Los niveles
Una misma idea se puede medir sobre elementos de distinto tamaño. Esta referencia usa siete niveles:
| Nivel | Qué es | Ejemplo de métrica |
|---|---|---|
| método | un método o un constructor | «v(G)» |
| clase | una clase, con sus métodos y campos | «WMC» |
| interfaz | una interfaz, medida aparte de las clases | «ISO» |
| paquete | un paquete de Java | «I» |
| módulo | un módulo del proyecto (un módulo del IDE, que suele corresponder a uno de Maven o Gradle) | «L(J)» |
| proyecto | todo el código analizado | «CF» |
| tipo de fichero | todos los ficheros de un tipo (Java, XML, texto…) | «FILES» |
Una página reúne el concepto en todos sus niveles. La
«cobertura Javadoc de métodos» (Jm), por ejemplo, se mide
en clases, interfaces, paquetes, módulos y proyecto, y sus seis variantes (dos de paquete, una de ellas
recursiva) están en la misma página, con un id de Stau Metro para cada una. Cuando las reglas de un nivel son muy
distintas, el concepto se parte: las «líneas de código de métodos, clases e interfaces»
y las «de paquetes, módulos, proyecto y tipos de fichero» tienen
páginas distintas.
Ojo. El mismo nombre en dos niveles no da números comparables. Un
NCLOCde 300 es enorme para un método y normal para una clase. Los umbrales de una métrica valen para el nivel en que se dan: el de 30 líneas del «NCLOC» de Stau Metro es solo para métodos.
Los tipos de valor
No todos los números se pueden tratar igual. La diferencia importa sobre todo al pasar de un nivel a otro.
Recuento. Cuenta elementos o líneas: parámetros, sentencias, clases. Un recuento de un nivel superior suele ser la suma de los del nivel inferior: las líneas de un paquete son las de sus ficheros. Es entero y casi siempre empieza en 0 (la complejidad ciclomática empieza en 1).
Puntuación o máximo. Es un valor de un solo elemento que no tiene sentido sumar. La
«profundidad de anidamiento» de un método es el nivel más profundo que
alcanza; sumar las profundidades de diez métodos no mide nada. Lo mismo ocurre con el tamaño de un conjunto, como el
número de clases distintas con las que se acopla una clase («CBO»):
dos clases acopladas con las mismas cinco no están acopladas con diez.
Media. Un valor medio sobre los elementos que contiene: la
«complejidad promedio de las operaciones» (OCavg) de una
clase es la media de sus métodos. Una media no se suma. En el nivel superior tampoco se promedian las medias: la
«complejidad ciclomática promedio» de un paquete es la media
de todos sus métodos, de modo que una clase con cien métodos pesa más que una con dos.
Proporción. El cociente entre una parte y un todo, casi siempre entre 0 y 1: qué parte de los métodos tiene Javadoc, qué parte del código es de test. Una proporción de nivel superior no es la media de las proporciones de los niveles inferiores: se suman por separado el numerador y el denominador y se divide al final. Así, cada método cuenta lo mismo, esté en una clase grande o en una pequeña. Stau Metro muestra estas proporciones como porcentaje. Unas pocas medidas entre 0 y 1, como la «inestabilidad», la «abstracción» y la «distancia a la secuencia principal», se muestran como número decimal; sus páginas lo indican.
Variantes recursivas de paquete. Para Java, com.example.app y com.example.app.web son dos paquetes
independientes: la especificación del lenguaje dice que la jerarquía de los nombres no tiene significado propio. Pero en
el disco y en la cabeza de quien programa, el segundo está dentro del primero. Por eso algunas métricas de paquete
tienen una variante recursiva, marcada con (rec) en la sigla: el valor de un paquete incluye el de todos sus
subpaquetes, sin contar nada dos veces. El «número de clases» C de com.example.app
cuenta solo las suyas; C(rec) cuenta también las de com.example.app.web. Hay recuentos recursivos y proporciones
recursivas.
Nota. Stau Metro llama a estos tipos
Count,Score,Average,Ratio,RecursiveCountyRecursiveRatio. La ficha de cada página dice cuál es en palabras, junto con el rango del valor.
La dirección
La dirección dice cómo se lee un valor alto:
- Más alto es peor. Complejidad, acoplamiento, tamaño de un método: cuanto más, más cuesta entender y cambiar.
- Más alto es mejor. Cobertura de documentación, proporción de código de test.
- Informativa: ni alto ni bajo es mejor. El número de clases de un paquete, las líneas de Java de un módulo, la inestabilidad de un paquete. Describen el código, pero un valor alto no es un defecto. Son la mayoría: en el catálogo de Stau Metro, 104 de los 142 conceptos son informativos.
Unas pocas métricas tienen una dirección intermedia, en la que un valor muy bajo y uno muy alto son malos (la «cohesión relacional»), o una dirección distinta en cada variante; la ficha lo dice.
Que una métrica sea informativa no la hace inútil. La «inestabilidad» no es buena ni mala por sí sola, pero combinada con la «abstracción» da la «distancia a la secuencia principal», que sí tiene dirección.
Los umbrales
Un umbral de referencia es el valor a partir del cual conviene mirar un elemento. Hay dos niveles:
- Aviso: el valor es alto (o bajo) para lo habitual; merece una mirada.
- Error: el valor es claramente anómalo; lo normal es que haya algo que corregir.
Una métrica puede tener los dos, solo uno o ninguno. El «LCOM»
de Stau Metro solo tiene aviso (por encima de 1); su
«número de dependencias cíclicas» de paquete solo tiene error (por
encima de 0). La mayoría de las métricas no tienen ninguno: en el catálogo de Stau Metro llevan umbral 13 métricas,
todas de dirección «más alto es peor».
Se superan de forma estricta. En una métrica en la que más alto es peor, el aviso salta cuando el valor es mayor que el umbral, no cuando es igual. Con un aviso de 10 para la complejidad ciclomática, un método que vale 10 no avisa y uno que vale 11 sí. En una métrica en la que más alto es mejor, sería al revés: cuando el valor es menor que el umbral.
Proporciones. Un umbral de una proporción se puede dar como fracción (0,2) o como porcentaje (20 %): es el mismo valor. El catálogo de Stau Metro guarda los umbrales de proporciones como fracción, aunque ninguna proporción lleva hoy umbral de referencia; un umbral propio para una proporción se escribe en el plugin como porcentaje, igual que se muestra el valor.
Procedencia. Cada umbral de esta referencia dice de dónde sale: «McCabe (1976)», «valor por defecto de Checkstyle», «umbral de referencia de Stau Metro». Las herramientas no coinciden, y muchos umbrales que circulan no tienen respaldo empírico. «De dónde salen los umbrales» lo explica; en la práctica, tómalos como el sitio donde empezar a mirar, no como una frontera entre código bueno y malo.
Mirar la distribución, no solo la media
Las métricas de código casi nunca se reparten de forma simétrica. En un proyecto típico, la mayoría de los métodos son cortos y sencillos y unos pocos concentran casi toda la complejidad. Por eso la media engaña.
Una clase con diez métodos, nueve sin ninguna decisión (complejidad ciclomática 1) y uno con veinte if seguidos
(21), tiene una media de . Su
«complejidad promedio de las operaciones» (OCavg) vale 3,
por debajo del aviso de 3,1 de Stau Metro, y la clase parece razonable; pero uno de sus métodos pasa el umbral de
error de v(G), que es 20. La
«complejidad máxima de las operaciones» (OCmax) de la
misma clase vale 21 y lo dice enseguida; por eso existe junto a la promedio.
Lo mismo pasa a mayor escala. Una «complejidad ciclomática promedio» de proyecto baja puede esconder una docena de métodos imposibles de probar, y una cobertura de Javadoc del 90 % en el proyecto puede esconder una interfaz pública sin una sola línea documentada.
Para leer bien un conjunto de valores:
- Mira los peores, no el promedio: ordena por la métrica y lee los diez primeros.
- Mira la forma: cuántos elementos pasan del umbral, no solo si la media lo pasa. Un histograma o unos percentiles (el valor que deja por debajo al 90 % de los elementos, por ejemplo) dicen más que una media.
- Compara con el propio proyecto: un valor es alto o bajo respecto a algo. El resto de las clases del mismo código es una referencia mejor que un umbral publicado para otro lenguaje.
«Agregar métricas» trata a fondo cómo se resumen los valores de muchos elementos.
Referencias
- The Java Language Specification, Java SE 21, apartado 7.1, «Package Members»: la estructura jerárquica de los nombres de paquete no tiene significado propio. https://docs.oracle.com/javase/specs/jls/se21/html/jls-7.html