Nivel inicial19 min de lectura · Publicado el

Complejidad ciclomática: qué es y cómo medirla

Complejidad ciclomática como un mapa de carreteras: en costeEnvio, tres if, un ternario y un && son cruces; 1 + 5 da 6 caminos. Cada if, un camino másrubentejera.com ifif?:if&&costeEnvio1 + 5 cruces= 6 caminos
En costeEnvio, cada decisión es un cruce: tres if, un ternario y un &&. Su complejidad es 1 + 5 = 6: seis caminos básicos que entender y, como mínimo, seis tests para recorrerlos.

Abres una función y encuentras if dentro de if, un switch y un par de &&. Antes de cambiar nada ya te duele la cabeza. La complejidad ciclomática pone un número a esa sensación: cuenta los caminos que puede seguir el código.

Piensa en el código como en un mapa de carreteras: cada if es un cruce. Una carretera sin cruces solo tiene un camino; cada cruce añade otro recorrido posible. La complejidad ciclomática cuenta esos recorridos, y cada uno es algo que tienes que entender y probar.

Qué es la complejidad ciclomática

Es una métrica que propuso Thomas J. McCabe en 1976, en el artículo «A Complexity Measure», publicado en IEEE Transactions on Software Engineering. Mide el número de caminos linealmente independientes de una función: los recorridos básicos a partir de los cuales se pueden construir todos los demás.

¿Por qué caminos básicos y no todos los caminos? Porque el total se dispara. McCabe pone el ejemplo de un programa de 50 líneas con 25 IF THEN seguidos: puede tener hasta 33,5 millones de caminos distintos. Su complejidad ciclomática, en cambio, es 26. Volviendo al mapa: no cuentas cada ruta posible entre dos ciudades, sino los tramos que tienes que conocer para poder construir cualquier ruta.

McCabe la planteó como alternativa a limitar los programas por su tamaño. Su artículo recoge que la complejidad no depende del tamaño: añadir instrucciones sin decisiones no la cambia; solo depende de la estructura de decisiones.

Para qué sirve:

  • Legibilidad: cuantos más caminos, más cosas tienes que tener en la cabeza a la vez.
  • Tests: indica cuántos casos de prueba necesitas para pasar por un conjunto básico de caminos.
  • Riesgo: las funciones con mucha complejidad son candidatas a esconder errores y a costar más de cambiar.

Cómo se calcula

El atajo para el día a día

No hace falta dibujar nada. Para una función basta con contar:

complejidad = 1 + número de puntos de decisión

Cuenta como punto de decisión cada if, else if, while, for, case, catch, operador ternario ? : y cada && o ||. El else no suma: es el otro lado del mismo cruce.

Los && y || suman porque se evalúan en cortocircuito: si la primera parte ya decide el resultado, la segunda no se ejecuta. En el código, if (a && b) equivale a un if (a) con un if (b) dentro. McCabe ya lo indicaba en 1976: las condiciones compuestas cuentan como dos.

Un ejemplo en JavaScript

// Calcula el coste de envío de un pedido
export function costeEnvio(pedido) {
  if (pedido.total >= 50) {          // +1
    return 0;
  }
  if (pedido.urgente) {              // +1
    return pedido.internacional ? 25 : 10; // +1 (ternario)
  }
  if (pedido.internacional && pedido.peso > 5) { // +1 (if) +1 (&&)
    return 15;
  }
  return 5;
}

Empiezas en 1 y sumas 5 decisiones: complejidad 6. Son los seis caminos de la portada: envío gratis, urgente nacional, urgente internacional, internacional pesado, internacional ligero y nacional.

El mismo ejemplo en Python

El cálculo no depende del lenguaje: cambian las palabras, no los cruces. En Python, and y or hacen el papel de && y ||, y el ternario se escribe x if condición else y.

def coste_envio(pedido):
    """Calcula el coste de envío de un pedido."""
    if pedido["total"] >= 50:                                  # +1
        return 0
    if pedido.get("urgente"):                                  # +1
        return 25 if pedido.get("internacional") else 10       # +1 (ternario)
    if pedido.get("internacional") and pedido["peso"] > 5:     # +1 (if) +1 (and)
        return 15
    return 5

También da 6. En Java, con if, && y ? :, el resultado es el mismo; se mide más abajo.

La fórmula del grafo

El atajo sale de una fórmula. McCabe representa la función como un grafo: los nodos son bloques de instrucciones que se ejecutan seguidos y las aristas, los saltos entre ellos.

M = E − N + 2P
  • E: número de aristas (flechas).
  • N: número de nodos (bloques).
  • P: número de componentes conectados; para una sola función, 1.

Con una función mínima se ve enseguida:

function tarifa(edad) {
  if (edad < 12) {
    return "infantil";
  }
  return "general";
}
Grafo de la función tarifa(edad): el nodo «edad < 12?» salta a «infantil» si se cumple o a «general» si no, y los dos llegan a «fin». Hay 4 nodos y 4 aristas, con P = 1: M = E − N + 2P = 4 − 4 + 2 × 1 = 2, lo mismo que el atajo, 1 + un if.
Cada caja es un nodo, un bloque de instrucciones, y cada flecha, una arista, un salto entre bloques. Debajo, la cuenta con la fórmula de McCabe.

Hay 4 nodos y 4 aristas: M = 4 − 4 + 2 × 1 = 2. Es lo mismo que da el atajo: 1 + un if. McCabe demuestra en su artículo que, en un programa estructurado, la fórmula del grafo equivale a contar las decisiones y sumar 1. Por eso en el día a día nadie dibuja el grafo.

Complejidad ciclomática y tests

El número también te dice cuántos tests necesitas como mínimo para recorrer un conjunto básico de caminos. La guía Structured Testing del NIST, escrita por Arthur H. Watson y el propio McCabe en 1996, lo plantea como criterio: probar un conjunto básico de caminos de cada módulo, de forma que cualquier otro camino se pueda expresar como combinación de los ya probados.

Para costeEnvio, seis casos recorren los seis caminos. Pero recorrer los caminos no es probar los límites: si alguien cambia >= por >, los seis siguen pasando. Por eso se añaden dos casos justo en la frontera, total: 50 y peso: 5. Estos tests se han ejecutado con node:test:

import { test } from "node:test";
import assert from "node:assert/strict";
import { costeEnvio } from "./envio.js";

const casos = [
  [{ total: 60 }, 0],                                            // gratis
  [{ total: 10, urgente: true, internacional: false }, 10],      // urgente nacional
  [{ total: 10, urgente: true, internacional: true }, 25],       // urgente internacional
  [{ total: 10, internacional: true, peso: 8 }, 15],             // internacional pesado
  [{ total: 10, internacional: true, peso: 2 }, 5],              // internacional ligero
  [{ total: 10, internacional: false, peso: 8 }, 5],             // nacional
  // Casos límite
  [{ total: 50 }, 0],                                            // justo en el mínimo
  [{ total: 10, internacional: true, peso: 5 }, 5],              // justo en el peso
];

for (const [pedido, esperado] of casos) {
  test(`${JSON.stringify(pedido)} → ${esperado}`, () => {
    assert.equal(costeEnvio(pedido), esperado);
  });
}

Los ejemplos usan import y export, así que el proyecto necesita "type": "module" en package.json (o ficheros .mjs). Ojo: npm init -y pone "type": "commonjs", y con eso Node falla con Cannot use import statement outside a module.

node --test envio.test.js
ℹ tests 8
ℹ pass 8
ℹ fail 0

(Extracto: las tres líneas del resumen final.) Se ha comprobado que los casos límite sirven: con total > 50 en lugar de total >= 50, o con peso >= 5 en lugar de peso > 5, falla un test; con solo los seis primeros, los dos cambios pasan desapercibidos.

Ojo con dos matices. El número es un mínimo para ese criterio, no una garantía de que no haya errores. Y la guía del NIST advierte de que a veces no todos los caminos se pueden recorrer con datos reales, por ejemplo cuando el código toma la misma decisión dos veces seguidas. Si te interesa escribir los tests antes que el código, mira qué es TDD.

Cómo medirla con herramientas

En un proyecto real, la complejidad la mide una herramienta. Los ejemplos de esta sección se han ejecutado; las versiones están en las fuentes.

JavaScript y TypeScript: la regla complexity de ESLint

ESLint trae la regla complexity. Su límite por defecto es 20; aquí se pone en 4 para ver el aviso con el ejemplo:

// eslint.config.js
export default [
  { files: ["**/*.js"], rules: { complexity: ["warn", 4] } },
];
npx eslint envio.js
2:8  warning  Function 'costeEnvio' has a complexity of 6. Maximum allowed is 4  complexity

Con "warn", ESLint avisa pero termina bien (código de salida 0). Con "error", termina con código 1, así que la integración continua (las comprobaciones que se ejecutan solas en cada cambio antes de aceptarlo) puede bloquearlo:

rules: { complexity: ["error", 10] }

La documentación de ESLint indica que, además de los if y los operadores lógicos, la regla cuenta los parámetros por defecto, los valores por defecto al desestructurar, cada ?. del encadenamiento opcional y los operadores ||= y &&=. Tiene también una variante, "modified", que cuenta cada switch como una sola decisión, tenga los case que tenga.

Python: radon

radon calcula la complejidad de cada función y le asigna una letra de la A a la F. Se instala con pip install radon:

radon cc -s envio.py
envio.py
    F 1:0 coste_envio - B (6)

-s muestra el número junto a la letra. La F del principio indica que es una función (no tiene que ver con la nota). Esta es la tabla de su documentación:

Complejidad Rango Riesgo según radon
1–5 A Bajo: bloque sencillo
6–10 B Bajo: bloque bien estructurado y estable
11–20 C Moderado: algo complejo
21–30 D Más que moderado
31–40 E Alto: complejo, alarmante
41 o más F Muy alto: propenso a errores, inestable

(Traducción nuestra de la documentación de radon.) Con radon cc -n C . ves solo las funciones de rango C o peor.

Casi cualquier lenguaje: lizard

lizard analiza la complejidad en una treintena de lenguajes, entre ellos Java, Kotlin, Python, JavaScript, TypeScript, C#, Go, Ruby y COBOL. Se instala con pip install lizard. Con la versión Java del ejemplo:

public class Envio {
    public static int costeEnvio(double total, boolean urgente, boolean internacional, double peso) {
        if (total >= 50) {                       // +1
            return 0;
        }
        if (urgente) {                           // +1
            return internacional ? 25 : 10;      // +1 (ternario)
        }
        if (internacional && peso > 5) {         // +1 (if) +1 (&&)
            return 15;
        }
        return 5;
    }

    public static void main(String[] args) {
        System.out.println(costeEnvio(60, false, false, 1));  // 0
        System.out.println(costeEnvio(10, true, true, 1));    // 25
        System.out.println(costeEnvio(10, false, true, 8));   // 15
    }
}
lizard Envio.java
  NLOC    CCN   token  PARAM  length  location
------------------------------------------------
      12      6     56      4      12 Envio::costeEnvio@[email protected]
       5      1     63      1       5 Envio::main@[email protected]

(Extracto: la tabla por función.)

La columna CCN es la complejidad ciclomática: 6, como en JavaScript y en Python. NLOC son las líneas de código sin comentarios ni líneas en blanco, token el número de piezas sueltas del código (palabras, símbolos, números) y PARAM el número de parámetros. Por defecto, lizard avisa cuando una función pasa de 15; con -C cambias el límite y con -w solo muestra los avisos. Si hay alguno, termina con código 1. Con el fichero de Python:

lizard -C 5 -w envio.py
envio.py:1: warning: coste_envio has 8 NLOC, 6 CCN, 54 token, 1 PARAM, 9 length, 0 ND

En Java también existe la regla CyclomaticComplexity de PMD, que según su documentación avisa por defecto en los métodos con complejidad de 10 o más. No se ha ejecutado para este artículo.

Por qué cada herramienta puede dar un número distinto

Con if, bucles y operadores lógicos, las herramientas coinciden. Con switch o match, no siempre. Esta función clasifica los días de la semana:

export function diaLaborable(dia) {
  switch (dia) {
    case "lunes":
    case "martes":
    case "miércoles":
    case "jueves":
    case "viernes":
      return true;
    case "sábado":
    case "domingo":
      return false;
    default:
      throw new Error(`Día desconocido: ${dia}`);
  }
}

ESLint le da 8 en su variante clásica (1 + un punto por cada case) y 2 en la variante "modified". La misma idea en Python, con match:

def dia_laborable(dia):
    match dia:
        case "lunes" | "martes" | "miércoles" | "jueves" | "viernes":
            return True
        case "sábado" | "domingo":
            return False
        case _:
            raise ValueError(f"Día desconocido: {dia}")

radon le da un 3 y lizard, un 4.

Ninguna está mal: cada una modela el switch a su manera. La guía del NIST explica que lo habitual es contar las sentencias con etiqueta, no cada etiqueta, aunque reconoce que contar cada etiqueta también es un modelo coherente. La conclusión práctica: compara números de la misma herramienta y con la misma configuración, no de herramientas distintas.

Qué valor es razonable

Esto es lo que dicen las fuentes:

  • McCabe (1976): el límite que usaba con los equipos era 10, que describe como un límite superior «razonable, pero no mágico» (traducción nuestra). Si una función pasaba de 10, había que dividirla o rehacerla. La única excepción que admitía era una función con muchos casos independientes tras una selección (un case largo).
  • Guía del NIST (1996): el 10 tiene un respaldo sólido, y se han usado con éxito límites de hasta 15. Pero reserva los límites por encima de 10 para equipos que cumplan, entre otras condiciones, estas: experiencia, diseño formal, revisiones de código y un plan de pruebas completo, y dispuestos a dedicar el esfuerzo de pruebas adicional.
  • Las herramientas: ESLint avisa por defecto cuando una función pasa de 20; lizard, cuando pasa de 15; PMD, desde 10 en los métodos Java; radon considera riesgo bajo hasta 10 y moderado de 11 a 20. Los criterios no son equivalentes: cada herramienta cuenta a su manera y usa su propio umbral.

Resumido en una tabla (explicación nuestra a partir de esas fuentes):

Complejidad Lectura orientativa
1–10 Manejable. Es el límite que usaba McCabe
11–15 Revísala: algunos equipos lo aceptan, pero ya cuesta seguirla
Más de 15 Candidata clara a dividirse en funciones más pequeñas

Por qué es una heurística y no una ley

El umbral es una regla práctica, no una frontera científica:

  • Mide caminos, no claridad. Un switch plano con diez casos suma mucho y se lee bien; tres if anidados suman poco y se leen mal. Para medir lo difícil que es de leer existe otra métrica, la complejidad cognitiva, que propuso G. Ann Campbell en SonarSource y que penaliza el anidamiento.
  • El número exacto depende de la herramienta, como acabas de ver con el switch.
  • Se puede «maquillar». La guía del NIST cuenta el caso de una «complejidad modificada» que dividía entre el número de ramas de los switch: bastaba con añadir un switch inútil de diez ramas para que una función de 90 pareciera de 10.
  • No ve lo que hay fuera de la función. Diez funciones de complejidad 3 pueden formar una clase imposible de entender.

Úsala como alarma: si salta, mira el código. No como nota que haya que aprobar.

Cómo reducirla

  • Cláusulas de guarda: sal pronto de la función en los casos especiales, en vez de anidar if. Los condicionales anidados son uno de los code smells más comunes, y la regla complexity con su umbral por defecto no siempre los ve.
  • Extrae funciones: cada decisión con nombre propio se entiende y se prueba por separado. Es lo que propone el capítulo de funciones en código limpio.
  • Sustituye switch largos por un objeto o un mapa de valores cuando solo eligen un dato.

Así queda costeEnvio extrayendo las decisiones:

const ENVIO_GRATIS_DESDE = 50;
const PESO_PESADO_KG = 5;
const TARIFA_URGENTE = { nacional: 10, internacional: 25 };
const TARIFA_INTERNACIONAL_PESADO = 15;
const TARIFA_ESTANDAR = 5;

const esEnvioGratis = (pedido) => pedido.total >= ENVIO_GRATIS_DESDE;
const esPesadoInternacional = (pedido) =>
  pedido.internacional && pedido.peso > PESO_PESADO_KG;
const tarifaUrgente = (pedido) =>
  pedido.internacional ? TARIFA_URGENTE.internacional : TARIFA_URGENTE.nacional;

export function costeEnvio(pedido) {
  if (esEnvioGratis(pedido)) return 0;
  if (pedido.urgente) return tarifaUrgente(pedido);
  if (esPesadoInternacional(pedido)) return TARIFA_INTERNACIONAL_PESADO;
  return TARIFA_ESTANDAR;
}

ESLint, con el límite en 1 para que muestre todas las funciones con alguna decisión:

   8:40  warning  Arrow function has a complexity of 2. Maximum allowed is 1         complexity
  10:32  warning  Arrow function has a complexity of 2. Maximum allowed is 1         complexity
  13:8   warning  Function 'costeEnvio' has a complexity of 4. Maximum allowed is 1  complexity

costeEnvio baja de 6 a 4, y esEnvioGratis se queda en 1. Fíjate en que la suma total no baja: sube de 6 a 9 (4 + 2 + 2 + 1): las decisiones siguen ahí, pero repartidas en piezas pequeñas con nombre, que se leen y se prueban por separado. Los ocho tests de antes pasan igual con esta versión.

Los números con nombre (ENVIO_GRATIS_DESDE, TARIFA_ESTANDAR…) no cambian la complejidad, pero ayudan a leerla: es la idea de los números mágicos.

Del método a la clase: el God Object

La complejidad ciclomática se mide por función. Cuando una clase acumula muchos métodos complejos y responsabilidades que no tienen nada que ver entre sí, el problema ya es de diseño: un God Object. La regla GodClass de PMD, por ejemplo, usa como una de sus señales la suma de la complejidad de los métodos de la clase. Y la complejidad que nadie limpia acaba convertida en deuda técnica.

El artículo de Joaquín Oriente

La versión original de esta página solo enlazaba a «Complejidad ciclomática: ¿nuestro código es fácil de mantener y probar?», de Joaquín Oriente (noviembre de 2012). Su web ya no responde, pero el texto se puede leer en una copia de Internet Archive de 2017. Es una introducción breve, en español y pensada para quien empieza:

  • Explica la métrica con el diagrama de flujo de una función que detecta si un año es bisiesto, que tiene tres caminos.
  • Calcula esos tres caminos de tres formas: contando recorridos, con la fórmula e − n + 2 (8 aristas, 7 nodos) y sumando 1 a las regiones cerradas del grafo.
  • Recoge una tabla de riesgo que atribuye a McCabe: hasta 10, sencillo; de 11 a 20, riesgo moderado; de 21 a 50, alto; más de 50, altísimo. El artículo no cita la publicación exacta de donde sale, así que tómala como orientación.
  • Advierte de que hay funciones complejas por naturaleza y de que trocearlas en exceso también puede empeorar el diseño.

Anunciaba una segunda parte sobre herramientas como SonarQube que no aparece en la copia archivada. Esta página cubre esa parte práctica con ESLint, radon y lizard.

Si el código lo escribe una IA

Un asistente de IA puede generar en segundos una función con diez if anidados que funciona y que nadie quiere tocar después. La regla complexity en el linter (la herramienta que revisa el código de forma automática), o lizard en la integración continua, es un aviso automático que no depende de que alguien lo vea en la revisión: si la función generada pasa del límite, toca pedir que la divida o dividirla antes de aceptar el cambio. Es una de las ideas de la IA Limpia: las métricas de siempre ponen límites a lo que acelera la IA.

Fuentes

  • Thomas J. McCabe, «A Complexity Measure», IEEE Transactions on Software Engineering, vol. SE-2, n.º 4, diciembre de 1976, pp. 308-320. Leído el 9 de noviembre de 2026 en una copia en PDF (copia no oficial; el texto coincide con la paginación de IEEE): definición con el grafo, el ejemplo de los 25 IF THEN, el límite de 10 («reasonable, but not magical»), la excepción del case largo, la equivalencia con contar predicados más 1 y las condiciones compuestas.
  • Arthur H. Watson y Thomas J. McCabe, Structured Testing: A Testing Methodology Using the Cyclomatic Complexity Metric, NIST Special Publication 500-235, 1996. Leída el 9 de noviembre de 2026: apartado 2.5 (límite de 10 y hasta 15, la «complejidad modificada»), apartado 4 (cómo contar && y switch) y apartado 5.1 (criterio de pruebas estructuradas).
  • Microsoft, Code metrics: cyclomatic complexity (actualizada el 30 de octubre de 2025), que cita el límite de 10 a 15 de la guía del NIST.
  • ESLint, regla complexity, consultada el 9 de noviembre de 2026: qué cuenta, límite por defecto (20) y variante "modified".
  • radon, documentación de la línea de comandos y qué cuenta, consultadas el 9 de noviembre de 2026: tabla de rangos A–F y opciones -s y -n.
  • PMD, reglas de diseño para Java, consultadas el 9 de noviembre de 2026: CyclomaticComplexity (avisa desde 10 por defecto) y GodClass. PMD no se ha ejecutado.
  • lizard, repositorio oficial y ayuda de lizard --help, consultados el 9 de noviembre de 2026: lenguajes compatibles, límite por defecto (15) y opciones -C y -w.
  • Joaquín Oriente, «Complejidad ciclomática: ¿nuestro código es fácil de mantener y probar?», 15 de noviembre de 2012. El dominio no responde en noviembre de 2026; leído en la copia de Internet Archive del 9 de diciembre de 2017.
  • Todo el código se ha ejecutado el 9 de noviembre de 2026; las salidas son las reales. JavaScript: ESLint 10.14.0 y node:test con Node.js 24.21.0. Python: radon 6.0.1 y lizard 1.25.1 con Python 3.15.2 (imagen Docker python:3). Java: OpenJDK 25.0.5 (imagen Docker eclipse-temurin:25). El grafo de tarifa y el cálculo con la fórmula se han hecho a mano; ESLint confirma que su complejidad es 2.