Métricas de código explicadas: ¿Qué es la complejidad ciclomática?

Estás revisando un pull request y una función ha crecido para manejar ocho condiciones diferentes: roles de usuario, feature flags, casos límite, fallbacks. Pasa las pruebas. Funciona. Pero algo no encaja. Esa sensación tiene un nombre y un número.

La complejidad ciclomática es una métrica de calidad de código que mide cuántas rutas de ejecución independientes existen a través de una función. Cuanto mayor sea el número, más lógica de ramificación contiene tu código, y más difícil resulta leerlo, probarlo y mantenerlo.

Cómo se calcula la complejidad ciclomática

Desarrollada por Thomas McCabe en 1976, la métrica se deriva del grafo de flujo de control de una función. La fórmula práctica para un único componente conectado es:

M = E − N + 2P

Donde E es el número de aristas, N es el número de nodos, P es el número de componentes conectados (normalmente 1 para una sola función) y M es la puntuación de complejidad.

Para la mayoría de los desarrolladores de JavaScript, no es necesario calcularlo manualmente. El atajo: empieza en 1 y luego suma 1 por cada sentencia de ramificación: if, else if, &&, ||, for, while, case, operadores ternarios y cláusulas catch. Algunas herramientas también cuentan construcciones como el encadenamiento opcional, los valores por defecto y la asignación lógica. Las reglas exactas de cálculo pueden variar ligeramente entre herramientas como ESLint y SonarQube.

Un ejemplo en JavaScript: cómo la ramificación incrementa la complejidad

// Cyclomatic complexity: 1
function getDisplayName(user: User): string {
  return user.name;
}

// Cyclomatic complexity: 6
function getDisplayName(user: User | null): string {
  if (!user) return "Guest";                     // +1
  if (user.isAdmin) return "Admin";              // +1
  if (user.displayName) return user.displayName; // +1
  if (user.firstName && user.lastName)           // +1 (if) +1 (&&)
    return `${user.firstName} ${user.lastName}`;
  return user.email;
}

Cada condición añade una rama. Más ramas significan más rutas que probar, y más maneras en que un cambio futuro podría romper algo de forma inesperada.

Este patrón aparece constantemente en el código de frontend: la lógica de renderizado de componentes React, los reducers de Redux con muchos tipos de acción, los handlers de validación de formularios y los flujos de UI basados en permisos.

Complejidad ciclomática vs. complejidad cognitiva

Son métricas relacionadas pero distintas. La complejidad ciclomática cuenta ramas estructurales: es una señal de testabilidad. La complejidad cognitiva (popularizada por SonarQube) mide qué tan difícil es de leer el código para un humano, penalizando con más fuerza el anidamiento y el flujo no lineal.

Una función puede obtener una puntuación baja en complejidad ciclomática y aun así ser difícil de seguir, por ejemplo, llamadas a métodos profundamente encadenadas sin variables intermedias. Ambas métricas son útiles, y ninguna cuenta la historia completa por sí sola.

Cómo medirla en tu codebase de JavaScript

Dos herramientas prácticas para equipos de frontend:

• Regla complexity de ESLint: señala las funciones que superan un umbral configurable directamente en tu editor.
• SonarQube / SonarCloud: reporta tanto la complejidad ciclomática como la cognitiva en todo tu codebase.

Configura ESLint así:

{
  "rules": {
    "complexity": ["warn", { "max": 10 }]
  }
}

El umbral es configurable, y debería serlo. Una utilidad de validación y un reducer de Redux no necesitan el mismo techo. Ajusta los umbrales al contexto de tu código, no a una regla universal.

Formas prácticas de reducir la complejidad innecesaria

Cuando la puntuación de una función aumenta, estas técnicas ayudan:

• Extraer funciones: separa la lógica diferenciada en helpers con nombre.
• Usar guard clauses: retorna de forma temprana en lugar de anidar condiciones.
• Simplificar condicionales: reemplaza cadenas booleanas complejas con variables descriptivas.
• Usar lookup tables: reemplaza sentencias switch largas con objetos o Map.

El objetivo no es obtener una puntuación baja por sí misma. Es tener código más fácil de probar, más fácil de modificar y más fácil de entender para el siguiente desarrollador.

Conclusión

La complejidad ciclomática te ofrece una señal concreta y medible sobre la lógica de ramificación en tu código. Usa ESLint o SonarQube para rastrearla, establece umbrales que se ajusten a tu codebase y trata las puntuaciones crecientes como un aviso para refactorizar, no como una crisis. Combínala con la complejidad cognitiva para obtener una visión más completa de la mantenibilidad.

Preguntas frecuentes

Gain control over your UX

See how users are using your site as if you were sitting next to them, learn and iterate faster with OpenReplay. — the open-source session replay tool for developers. Self-host it in minutes, and have complete control over your customer data. Check our GitHub repo and join the thousands of developers in our community.