Complejidad cognitiva

Actualizado el 15 de noviembre de 2026

Sigla CogC
Aspecto «Complejidad»
Se mide en método
Tipo de valor recuento (entero, mínimo 0)
Dirección más alto es peor
Umbrales de referencia aviso por encima de 15, error por encima de 25 (Stau Metro)
Origen G. Ann Campbell (SonarSource): informe técnico (versión 1.1, 2017) y artículo (2018)
Stau Metro CognitiveComplexity

En pocas palabras

Mide cuánto esfuerzo cuesta seguir un método al leerlo. Cada if, bucle o catch suma un punto, y suma más cuanto más metido está dentro de otras estructuras. Un método sin decisiones vale 0. Cuatro if en fila valen 4; cuatro if uno dentro de otro valen 10 (1 + 2 + 3 + 4).

Qué mide

Mide la dificultad de comprensión del flujo de control, no el número de caminos. Parte de tres intuiciones:

  • Cada vez que el código deja de leerse de arriba abajo (una condición, un bucle, un salto) el lector tiene que guardar algo en la cabeza.
  • Una estructura dentro de otra cuesta más que dos estructuras seguidas, porque el lector tiene que recordar todas las condiciones que le han llevado hasta ahí.
  • Las abreviaturas que hacen el código más claro no deben castigarse. Extraer un método, por ejemplo, no suma nada.

Importa porque el coste principal de un método no está en escribirlo, sino en las veces que alguien tiene que leerlo para cambiarlo. Un método con una complejidad cognitiva alta es un método donde es fácil introducir un error al tocarlo.

Para quien empieza. Llamamos anidamiento a meter una estructura de control dentro de otra: un if dentro de un for está en el nivel 1 de anidamiento; un while dentro de ese if, en el nivel 2.

Cómo se calcula

La definición está en el informe técnico de SonarSource Cognitive Complexity: a new way of measuring understandability (Campbell). El valor empieza en 0 y se suman cuatro tipos de incremento, todos de 1 punto:

Incremento Se aplica a Suma
Estructural if, operador ? :, switch, for, foreach, while, do … while, catch 1 + el nivel de anidamiento en que está
Híbrido else if, else 1, sin extra por anidamiento
Fundamental cada secuencia de operadores lógicos iguales; break o continue a una etiqueta; goto; cada método de un ciclo de recursión 1, sin extra por anidamiento
Anidamiento lo que suman los estructurales por estar dentro de otros 1 por nivel

Suben el nivel de anidamiento los mismos if, else if, else, ? :, switch, bucles y catch, y además los métodos anidados y las lambdas, que suben el nivel pero no suman por sí mismos. No suman nada ni suben el nivel el propio método, try, finally, los case de un switch (el switch entero suma 1), los return anticipados, los break y continue sin etiqueta, ni los operadores que abrevian, como el ?. de otros lenguajes.

Secuencias de operadores lógicos. No se cuenta cada && o ||, sino cada cambio de operador al leer la expresión: a && b && c && d suma 1; a || b && c || d suma 3, porque hay tres tramos de operadores iguales. El informe técnico explica que entender una cadena de operadores iguales cuesta poco más que entender uno solo, y que lo que cuesta es mezclarlos.

Ejemplo

static int score(List<Order> orders, boolean strict) {
    int total = 0;
    for (Order order : orders) {                            // +1 (nivel 0)
        if (order.isCancelled()) {                          // +2 (1 + nivel 1)
            continue;                                       // sin etiqueta: no suma
        }
        if (strict && order.isLate() || order.isLost()) {   // +2 (1 + nivel 1), +2 (tramos && y ||)
            total -= order.penalty();
        } else if (order.isPaid()) {                        // +1 (else if)
            total += order.amount() > 100 ? 2 : 1;          // +3 (1 + nivel 2)
        } else {                                            // +1 (else)
            total++;
        }
    }
    return total;
}

Total: 1 + 2 + 2 + 2 + 1 + 3 + 1 = 12. Por debajo del umbral de 15.

Fíjate en de dónde salen los puntos: el ? : vale 3 por sí solo porque está dos niveles dentro (el for y el if). Si el cuerpo del bucle se extrajera a un método scoreOne(order, strict), ese método valdría 8 y el original 1: la lógica no cambia, pero ningún trozo exige recordar más de un nivel.

La complejidad ciclomática del mismo método es 8. La diferencia la hacen el anidamiento, que la ciclomática no ve, y el else, que la ciclomática no cuenta porque no es una decisión nueva.

Cómo interpretarla

Valor Lectura habitual
0-15 Dentro del límite habitual: se sigue sin esfuerzo especial
16-25 Difícil de seguir: conviene simplificarlo
Más de 25 Candidato claro a refactorización

Los dos cortes tienen procedencia: 15 es el umbral por defecto de la regla de SonarQube para Java (S3776) y de la regla CognitiveComplexity de PMD; 25 es el umbral por defecto de la comprobación readability-function-cognitive-complexity de clang-tidy, para C y C++. Stau Metro usa aviso por encima de 15 y error por encima de 25.

Qué hacer con un valor alto:

  • Aplana con cláusulas de guarda. Un if (!valido) return; al principio saca de un nivel todo lo que viene después.
  • Extrae métodos. El informe técnico lo presenta como el remedio natural: un método con buen nombre es una abreviatura que no suma.
  • Separa las condiciones mezcladas. if (a && b || c) puede convertirse en una variable o un método con nombre (boolean urgente = …).
  • Sustituye cadenas de if … else if por un switch, que suma 1 en total, cuando todas comparan el mismo valor.

Cuándo un valor alto es aceptable. En analizadores, máquinas de estados o algoritmos que son intrínsecamente anidados, partir el método puede esparcir la lógica sin hacerla más clara. Y como la métrica es una suma, un método largo con muchos if planos llega a 15 sin ser difícil: en ese caso mira el detalle antes de refactorizar.

Ojo. No compares a ciegas la complejidad cognitiva con la ciclomática ni uses los umbrales de una para la otra. Un switch de veinte casos vale 21 en ciclomática y 1 en cognitiva.

Para profundizar

Por qué se propuso. El informe técnico parte de dos métodos con la misma complejidad ciclomática, 4: un switch de tres casos que traduce números a palabras, y un doble bucle con un if y un continue etiquetado que suma números primos. El primero vale 1 en complejidad cognitiva; el segundo, 7. La crítica de fondo es que la complejidad ciclomática mide bien la facilidad de prueba, pero no la de comprensión.

Agregación. Como un método vacío vale 0 (y no 1, como en la ciclomática), sumar la métrica sobre una clase sí distingue una clase con cien getters de una clase pequeña con un método enrevesado. El informe técnico presenta esto como una de sus ventajas.

Propiedades y límites.

  • No es una medida derivada de un modelo. La autora renuncia a propósito a un modelo matemático y fija las reglas por juicio humano, convirtiendo en números la intuición de los programadores. Eso la hace intuitiva, pero también arbitraria en los detalles: por qué un catch suma lo mismo que un if, o por qué un else suma.
  • Ignora los datos y los nombres. Un método con condiciones planas pero variables mal nombradas, expresiones largas o estado mutable compartido puede ser muy difícil de leer y valer poco.
  • Depende del lenguaje. El propio informe técnico admite excepciones por lenguaje (el else if que falta en COBOL, los decoradores de Python) para no castigar idiomas comunes.

Evidencia empírica. Muñoz Barón, Wyrich y Wagner (2020) reunieron evaluaciones de comprensión de código de varios estudios previos y encontraron que la complejidad cognitiva se correlaciona con el tiempo que se tarda en comprender un fragmento y con la valoración subjetiva de su dificultad, con resultados mixtos para el acierto en tareas de comprensión y para las medidas fisiológicas. Los autores la presentan como la primera validación empírica de la métrica; no es la última palabra.

Versiones del informe. El documento ha cambiado de versión varias veces. La 1.1 (febrero de 2017) incluyó la recursión indirecta y el incremento híbrido de else y else if; la 1.2 (abril de 2017) añadió el apéndice con la especificación, que es la versión que cita clang-tidy; la 1.7 es de agosto de 2023.

Relación con otras métricas

En las herramientas

Stau Metro (CognitiveComplexity, a nivel de método). Aplica la especificación con estas reglas:

  • suman 1 más el nivel de anidamiento: if (no el else if), ? :, for, for mejorado, while, do … while, catch, y el switch tanto de sentencia como de expresión (los case, las reglas -> y las guardas when no suman);
  • suman 1 sin anidamiento: cada else if y cada else, cada break o continue con etiqueta, y cada secuencia de operadores && o || iguales leída de izquierda a derecha;
  • una secuencia entre paréntesis cuenta aparte: a && (b && c) suma 2;
  • la recursión cuenta solo si es directa: un método que se llama a sí mismo suma 1, una sola vez aunque haya varias llamadas, y también si la llamada está dentro de una lambda del método; la recursión indirecta (a llama a b, que llama a a) no suma;
  • suben el nivel sin sumar las lambdas y los métodos de clases anónimas o locales;
  • una estructura anida todo lo que contiene, también su condición: un ? : o una lambda escritos en la condición de un if, en la cabecera de un bucle o en el selector de un switch ya están un nivel dentro (if (a ? b : c), en el nivel 0, suma 1 + 2 = 3).

No se calcula para métodos abstractos. Los constructores cuentan como métodos. Los métodos de clases anónimas y locales declaradas dentro de un método no tienen valor propio: su complejidad, con el nivel extra, se suma al método que las contiene. Los bloques de inicialización (static { … }) no se miden.

SonarQube (analizador de Java, regla S3776, Cognitive Complexity of methods should not be too high). Umbral por defecto 15. En su código fuente, la secuencia de operadores se calcula saltándose los paréntesis, de modo que a && (b && c) suma 1; la llamada recursiva no suma, y la condición de un if se evalúa al nivel del propio if, así que if (a ? b : c) suma 2. Los métodos de clases anónimas y locales no se puntúan por separado.

PMD (regla CognitiveComplexity). Remite al informe técnico de SonarSource e informa de los métodos con complejidad 15 o más (reportLevel). Fíjate en que PMD avisa con 15; Stau Metro, con más de 15.

clang-tidy (readability-function-cognitive-complexity, para C y C++). Sigue la especificación en su versión 1.2 y avisa por encima de 25 (Threshold). Su documentación advierte que no cuenta los ciclos de recursión, porque exigirían analizar varias unidades de compilación.

MetricsReloaded (plugin de IntelliJ). Calcula CogC para cada método no abstracto.

Referencias