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 |
En pocas palabras
Cuenta cuántas veces un método tiene que decidir por dónde seguir. Un método sin if, sin bucles y sin switch
vale 1: solo hay una forma de recorrerlo. Cada decisión que se añade suma 1. Cuanto más alto es el número, más
casos hay que tener en la cabeza para entender el método y más tests hacen falta para probarlo.
Qué mide
Mide la cantidad de lógica de decisión de un método, sin fijarse en su tamaño. Un método de doscientas líneas que solo asigna campos vale 1; uno de quince líneas con seis condiciones encadenadas vale 7.
Importa por dos razones prácticas:
- Tests. El valor dice cuántos caminos independientes tiene el método, es decir, cuántos tests hacen falta como mínimo para ejercitar cada decisión en sus dos sentidos siguiendo el método de McCabe (ver «Para profundizar»).
- Comprensión y cambio. Cada decisión es un sitio donde el comportamiento se bifurca y donde puede esconderse un caso no previsto. Los métodos con muchas decisiones son los que más cuesta modificar sin romper algo.
Para quien empieza. No hace falta dibujar ningún grafo para calcularla. Basta con contar: empieza en 1 y suma 1 por cada
if, cada bucle, cadacasey cada&&o||.
Cómo se calcula
McCabe la definió sobre el grafo de flujo de control del método: cada nodo es un bloque de sentencias que se ejecutan seguidas, y cada arista, un salto posible de un bloque a otro. Con aristas, nodos y componentes conexos (en un solo método, ):
Para código estructurado, con una sola entrada y una sola salida, la fórmula equivale a algo mucho más fácil de aplicar:
Una decisión con más de dos salidas cuenta como tantas decisiones binarias como salidas tenga menos una: un
switch con cuatro case y un default son cuatro decisiones.
En la práctica nadie construye el grafo. Las herramientas recorren el árbol sintáctico y suman 1 por cada construcción que bifurca el flujo. Qué construcciones cuentan es donde las herramientas discrepan (ver «En las herramientas»); lo habitual en Java es:
| Construcción | Suma |
|---|---|
if |
1 (el else no suma: es la otra salida de la misma decisión) |
for, for mejorado, while, do … while |
1 cada uno |
case de un switch |
1 por cada alternativa; default no suma |
Operador condicional ? : |
1 |
&& y || |
1 por cada operador (variante «extendida») |
catch |
1, según la herramienta |
Ejemplo
Order y Customer son clases cualesquiera; tier() devuelve un enumerado con las constantes GOLD, SILVER y
alguna más.
static String classify(List<Order> orders, Customer customer) { // 1 (el método)
if (orders == null || orders.isEmpty()) { // +1 if, +1 ||
return "empty";
}
int urgent = 0;
for (Order order : orders) { // +1 for
if (order.isPaid() && order.isLate()) { // +1 if, +1 &&
urgent++;
}
}
return switch (customer.tier()) {
case GOLD -> urgent > 0 ? "call" : "ok"; // +1 case, +1 ?:
case SILVER -> "email"; // +1 case
default -> "wait"; // default no suma
};
}
Total: 1 + 2 + 1 + 2 + 2 + 1 = 9. El método queda justo por debajo del umbral clásico de 10.
Fíjate en que el return anticipado no suma nada: no es una decisión, sino una de las dos salidas del if que ya
se ha contado. Y en que las dos condiciones compuestas aportan cuatro de los nueve puntos; una herramienta que no
cuente && y || daría 7 para este mismo método.
Cómo interpretarla
| Valor | Lectura habitual |
|---|---|
| 1-10 | Método sencillo, fácil de probar |
| 11-20 | Complejidad moderada: conviene mirarlo |
| 21-50 | Complejo, difícil de probar por completo |
| Más de 50 | Prácticamente imposible de probar por completo |
El límite de 10 es de McCabe, que en el artículo de 1976 lo propuso como «un límite superior razonable, aunque no mágico». El informe NIST 500-235 de Watson y McCabe (1996) lo mantiene como valor por defecto y admite límites de hasta 15 en equipos con experiencia, diseño formal y un plan de tests completo. La tabla de cuatro tramos de arriba suele atribuirse al Software Engineering Institute y la repiten muchas herramientas; tómala como una orientación, no como una norma.
Stau Metro usa como referencia aviso por encima de 10 y error por encima de 20. Checkstyle y PMD traen 10 como límite por defecto.
Qué hacer con un valor alto:
- Extrae métodos. Un bloque
ifo el cuerpo de un bucle con lógica propia suele ser un método con nombre esperando a salir. La complejidad total no desaparece, pero se reparte en piezas que se entienden y se prueban por separado. - Sustituye condicionales por polimorfismo o por una tabla. Un
switchsobre un tipo que se repite en varios métodos es candidato a una jerarquía o a unMapde estrategias. - Simplifica las condiciones. Cláusulas de guarda al principio, condiciones con nombre (
isEligible(order)) y eliminación de casos imposibles.
Cuándo un valor alto es aceptable. Un switch plano que traduce veinte códigos a veinte mensajes vale 21 y se
lee de un vistazo. Esa es la principal debilidad de la métrica: no distingue veinte casos en fila de veinte
decisiones anidadas. Para eso están la «complejidad cognitiva» y la
«profundidad de anidamiento».
Ojo. La complejidad ciclomática no mide lo difícil que es leer un método, sino cuántos caminos tiene. Dos métodos con el mismo valor pueden ser muy distintos de entender.
Para profundizar
Qué significa «caminos independientes». es el número ciclomático del grafo: la dimensión de su espacio de ciclos. En términos de tests, es el tamaño de un conjunto base de caminos: un conjunto de caminos tal que cualquier otro camino del método se puede expresar como combinación lineal de ellos. De ahí salen las dos cotas que se citan siempre, a veces mal:
- es una cota superior del número de tests necesarios para cubrir todas las ramas;
- es una cota inferior del número de caminos posibles del método (que, con decisiones en secuencia, crece de forma multiplicativa: es lo que cuenta la «complejidad NPath»).
No es, por tanto, «el número de tests para cubrir todos los caminos». El método de prueba estructurada de McCabe (basis path testing) pide exactamente tests, uno por cada camino del conjunto base.
Variantes. McCabe contaba predicados y ya advertía que una condición compuesta equivale a varias decisiones. Myers (1977) propuso contarlas de forma explícita, y de ahí sale la variante más extendida hoy:
- Estricta o extendida (a veces
CC2): cada&&y||suma 1, porque el cortocircuito crea de verdad una rama. Es lo que hacen Stau Metro, Checkstyle y SonarQube. - Sin operadores lógicos: solo cuentan las sentencias de control;
if (a && b)suma 1. - Modificada (a veces
CC3): unswitchentero cuenta como una sola decisión, sea cual sea su número decase, y los operadores lógicos no suman. Checkstyle ofrece como opción esa forma de contar elswitch, sin dejar de contar&&y||.
Críticas conocidas.
- Se correlaciona mucho con el tamaño. Shepperd (1988) revisó la evidencia y concluyó que, en muchos conjuntos de datos, la complejidad ciclomática aporta poco más que las líneas de código. Conviene leerla junto a las «líneas de código sin comentarios» y sospechar cuando las dos señalan lo mismo.
- Ignora el anidamiento. Tres
ifen fila y tresifuno dentro de otro valen lo mismo. Fue la motivación directa de la complejidad cognitiva (Campbell, 2018). - Ignora los datos. No ve la complejidad que vive en las estructuras de datos, en las expresiones o en las llamadas; las «medidas de Halstead» miran justo lo que esta no mira.
- No cumple varias de las propiedades de Weyuker (1988) para una medida de complejidad; por ejemplo, no cambia al reordenar las sentencias de un programa.
- Castiga construcciones inofensivas. Los
switchplanos, las comprobaciones denullencadenadas y el código generado inflan el valor sin que el método sea difícil.
Excepciones. No hay acuerdo sobre catch, throw ni finally. Un catch es, en rigor, una rama que parte de
cada sentencia del try que puede lanzar la excepción; contar 1 por catch es una simplificación corriente, y no
contarlo, otra.
Agregación. Sumar sobre los métodos de una clase da una medida del tamaño lógico de la clase (es una de
las formas de calcular WMC); la media por método dice más sobre el estilo del código que sobre su volumen. Ni la
suma ni la media sustituyen a mirar los máximos: la distribución es muy asimétrica y unos pocos métodos concentran
casi toda la complejidad.
Relación con otras métricas
- «Complejidad ciclomática esencial» (
ev(G)): lo que queda dev(G)después de descontar las decisiones bien estructuradas. Señala el código con saltos que rompen la estructura. - «Complejidad de diseño» (
iv(G)): la parte dev(G)que interviene en las llamadas a otros métodos. - «Complejidad cognitiva» (
CogC): cuenta casi las mismas construcciones, pero penaliza el anidamiento. Se leen juntas:v(G)alta conCogCbaja suele ser unswitchplano. - «Profundidad de anidamiento» (
NBD): la dimensión quev(G)no ve. - «Complejidad NPath»: cuenta caminos completos, no independientes; crece mucho más deprisa.
- «Complejidad ponderada de los métodos» (
WMC), «complejidad promedio» (OCavg) y «máxima de las operaciones» (OCmax): la agregan a nivel de clase. - «Complejidad ciclomática promedio» (
v(G)avg) y «total» (v(G)tot): la agregan por paquete, módulo y proyecto. - «Líneas de código sin comentarios» (
NCLOC): se correlaciona con ella; un método largo casi siempre tiene más decisiones. - «Cobertura de código»:
v(G)acota los tests necesarios para la cobertura de ramas. - «Índice de mantenibilidad»: la usa como uno de sus tres ingredientes.
En las herramientas
Las herramientas no dan el mismo número para el mismo método. Antes de comparar valores entre dos herramientas, o de aplicar un umbral publicado, hay que saber qué cuenta cada una.
| Herramienta | && y || |
catch |
case |
Sobre |
|---|---|---|---|---|
| Stau Metro | sí | sí | uno por grupo o regla, sin default |
código fuente |
| Checkstyle | sí | sí | uno por case (opción: todo el switch como 1) |
código fuente |
| SonarQube (Java) | sí | no figura | uno por case |
código fuente |
| JaCoCo | las ramas que genere el compilador | no | las ramas que genere el compilador | bytecode |
Stau Metro (CyclomaticComplexity, a nivel de método). Empieza en 1 y suma:
- 1 por cada
if,for,formejorado,while,do … whiley operador? :; - 1 por cada
catch; - en una cadena de
&&o de||, 1 por cada operando después del primero (a && b && csuma 2), esté o no en una condición:return a && b;también suma 1; - en un
switchclásico (con dos puntos), 1 por cada grupo de etiquetas seguido de sentencias, de modo quecase 1: case 2: foo();suma 1 y no 2; el grupo que contienedefaultno suma, ni tampoco una etiqueta final sin sentencias detrás; - en un
switchcon flechas, sea sentencia o expresión, 1 por cada regla que no seadefault; - 1 más por cada guarda
whende un patrón.
No se calcula para métodos abstractos, ni para los métodos sin cuerpo de una interfaz; un método native vale 1.
Los constructores cuentan como métodos. Las decisiones de las lambdas y de las clases anónimas o locales declaradas
dentro de un método se suman al método que las contiene, y esos métodos internos no tienen valor propio. Sí lo
tienen los métodos de una clase anónima creada en un inicializador de campo y los de los cuerpos de las constantes
de un enumerado. Entra también el código de test.
Las métricas de clase WMC, OCavg y OCmax de Stau Metro usan un recuento distinto, que no incluye ni los
operadores && y || ni los catch. Por eso el WMC de una clase puede ser menor que la suma de la v(G) de
sus métodos. Las agregadas v(G)avg y v(G)tot sí usan el mismo recuento que esta métrica.
Checkstyle (CyclomaticComplexity). Número de puntos de decisión más 1. Su documentación da como puntos de
decisión if, while, do, for, ?:, catch, switch, case, los operadores && y || y las guardas
when. Según su código, con la configuración por defecto suma cada case y no el switch en sí; con
switchBlockAsSingleDecisionPoint es al revés: cada switch cuenta como una sola decisión. El máximo por defecto
es 10.
PMD (regla CyclomaticComplexity). Puntos de decisión más 1 por la entrada al método. Informa de los métodos
con complejidad 10 o más y de las clases cuya suma llega a 80. Tiene dos opciones de cálculo, ignoreBooleanPaths
y considerAssert.
SonarQube (analizador de Java). Calcula la complejidad a nivel de método y suma 1 por cada if, for,
while, case, &&, ||, ? y ->.
JaCoCo. No analiza el código fuente, sino el bytecode, con , donde es el número de
ramas y el de puntos de decisión. Como cuenta los saltos condicionales que emite el compilador, incluye los
que salen de && y ||. Los bloques try/catch no aumentan la complejidad.
Referencias
- McCabe, T. J. (1976). «A Complexity Measure». IEEE Transactions on Software Engineering, SE-2(4), 308-320. https://ieeexplore.ieee.org/document/1702388
- Myers, G. J. (1977). «An Extension to the Cyclomatic Measure of Program Complexity». ACM SIGPLAN Notices, 12(10), 61-64.
- Watson, A. H. y McCabe, T. J. (1996). Structured Testing: A Testing Methodology Using the Cyclomatic Complexity Metric. NIST Special Publication 500-235.
- Shepperd, M. (1988). «A Critique of Cyclomatic Complexity as a Software Metric». Software Engineering Journal, 3(2), 30-36.
- Weyuker, E. J. (1988). «Evaluating Software Complexity Measures». IEEE Transactions on Software Engineering, 14(9), 1357-1365.
- Campbell, G. A. (2018). «Cognitive Complexity: An Overview and Evaluation». Proceedings of the 2018 International Conference on Technical Debt, 57-58.
- Aivosto, Complexity metrics (variantes CC, CC2 y CC3): https://www.aivosto.com/project/help/pm-complexity.html
- Checkstyle, comprobación
CyclomaticComplexity: https://checkstyle.sourceforge.io/checks/metrics/cyclomaticcomplexity.html; código de la comprobación: https://github.com/checkstyle/checkstyle - PMD, reglas de diseño para Java: https://docs.pmd-code.org/latest/pmd_rules_java_design.html
- SonarQube, definición de métricas: https://docs.sonarsource.com/sonarqube-server/latest/user-guide/code-metrics/metrics-definition/
- JaCoCo, contadores de cobertura: https://www.jacoco.org/jacoco/trunk/doc/counters.html