Complejidad cognitiva
| 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
ifdentro de unforestá en el nivel 1 de anidamiento; unwhiledentro de eseif, 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 ifpor unswitch, 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
switchde 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
catchsuma lo mismo que unif, o por qué unelsesuma. - 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 ifque 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
- «Complejidad ciclomática» (
v(G)): cuenta casi las mismas construcciones, pero sin anidamiento, con cadacasey cada&&por separado, y con 1 de partida. Se leen juntas:v(G)alta conCogCbaja suele ser unswitchplano;CogCmucho más alta quev(G)señala anidamiento. - «Profundidad de anidamiento de bloques» (
NBD): mide solo el nivel máximo; la complejidad cognitiva lo convierte en un coste que se acumula en cada estructura. - «Profundidad de anidamiento condicional» (
IF_NEST) y «de bucles» (LOOP_NEST): desglosan por tipo de estructura dónde está el anidamiento. - «Número de sentencias de control» (
CONTROL): el recuento sin pesos de las mismas estructuras. - «Complejidad NPath»: también crece con el anidamiento, pero porque cuenta caminos completos.
- «Líneas de código sin comentarios» (
NCLOC): los métodos largos tienden a sumar más; compara las dos antes de concluir que un método es complejo y no solo largo.
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 elelse if),? :,for,formejorado,while,do … while,catch, y elswitchtanto de sentencia como de expresión (loscase, las reglas->y las guardaswhenno suman); - suman 1 sin anidamiento: cada
else ify cadaelse, cadabreakocontinuecon 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 (
allama ab, que llama aa) 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 unif, en la cabecera de un bucle o en el selector de unswitchya 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
- Campbell, G. A. Cognitive Complexity: a new way of measuring understandability. Informe técnico de SonarSource, versión 1.7, 29 de agosto de 2023. https://www.sonarsource.com/docs/CognitiveComplexity.pdf
- Campbell, G. A. (2018). «Cognitive Complexity: An Overview and Evaluation». Proceedings of the 2018 International Conference on Technical Debt, 57-58.
- Muñoz Barón, M., Wyrich, M. y Wagner, S. (2020). «An Empirical Validation of Cognitive Complexity as a Measure of Source Code Understandability». Proceedings of the 14th ACM/IEEE International Symposium on Empirical Software Engineering and Measurement (ESEM 2020). https://arxiv.org/abs/2007.12520
- SonarSource, analizador de Java,
CognitiveComplexityMethodCheckyCognitiveComplexityVisitor: https://github.com/SonarSource/sonar-java - PMD, reglas de diseño para Java: https://docs.pmd-code.org/latest/pmd_rules_java_design.html
- clang-tidy,
readability-function-cognitive-complexity: https://clang.llvm.org/extra/clang-tidy/checks/readability/function-cognitive-complexity.html - MetricsReloaded: https://github.com/BasLeijdekkers/MetricsReloaded