τTau SolutionsAspectos de calidad

Guía del aspecto: Complejidad

Actualizado el 15 de noviembre de 2026

El aspecto de complejidad responde a una pregunta: ¿cuánta lógica hay que tener en la cabeza para entender, probar o cambiar este trozo de código? El tamaño dice cuánto código hay; la complejidad dice lo enrevesado que es. Un método de doscientas líneas que solo asigna campos es grande y sencillo. Uno de quince líneas con seis condiciones anidadas es pequeño y complejo.

Casi todas las métricas del aspecto se miden en el método, porque es la unidad que se lee de una vez. Las de clase, paquete, módulo y proyecto agregan esos valores. Lo que se cuenta cambia de una familia a otra:

  • las decisiones: cada if, bucle, case o && es un sitio donde el flujo se bifurca (familia de McCabe);
  • el anidamiento: lo hondo que están unas estructuras dentro de otras (complejidad cognitiva y profundidades);
  • los caminos completos: cómo se combinan las decisiones que van en secuencia (NPath);
  • los tokens: cuántos operadores y operandos hay y cuántos distintos (medidas de Halstead), o solo las asignaciones, llamadas y condiciones (métrica ABC);
  • ingredientes sueltos: parámetros, bucles, saltos, comprobaciones de null, excepciones.

Para quien empieza. Ninguna de estas métricas mide si el código es correcto. Miden cuánto cuesta convencerse de que lo es. Un valor alto no es un defecto; es un sitio donde los defectos tienen más donde esconderse.

Por dónde empezar

Tres métricas cubren lo esencial a nivel de método:

  1. «Complejidad ciclomática» (v(G)): cuántas decisiones toma el método. La más antigua de las tres y la que calculan casi todas las herramientas.
  2. «Complejidad cognitiva» (CogC): cuánto cuesta seguirlo al leerlo; castiga el anidamiento.
  3. «Profundidad de anidamiento de bloques» (NBD): hasta dónde baja el bloque más profundo.

Añade el «número de parámetros» (NP) para ver lo difícil que es llamar al método, y la «complejidad ponderada de los métodos» (WMC) para pasar a la clase. Esas cinco son las que el catálogo de Stau Metro marca como esenciales en este aspecto. Si te interesa un recorrido general, mira «Primeros pasos».

Ciclomática, cognitiva o NPath

Las tres miran el flujo de control de un método y cuentan casi las mismas construcciones. Difieren en lo que hacen con ellas, y por eso responden a preguntas distintas.

Ciclomática v(G) Cognitiva CogC NPath NPATH
Qué cuenta decisiones (caminos independientes) rupturas del flujo lineal, pesadas por anidamiento caminos completos (combinaciones de ramas)
Cómo combina suma suma, con recargo por nivel multiplica lo que va en secuencia
Método sin decisiones 1 0 1
Pregunta que contesta ¿cuántos tests pide la prueba estructurada? ¿cuánto cuesta leerlo? ¿cuántas combinaciones de decisiones hay?
Umbral habitual 10 (McCabe; Checkstyle y PMD) 15 (SonarQube y PMD) 200 (grupo de Nejmeh; Checkstyle y PMD)
Stau Metro la calcula la calcula no la calcula

La diferencia se ve mejor con un ejemplo. Toma if sin else, con una condición simple y una sola sentencia en el cuerpo, y colócalos en fila o uno dentro de otro. Para NPath se usa el criterio de Checkstyle y PMD, que dan 1 a cada sentencia simple:

Forma v(G) CogC NPATH
dos if en fila 3 2 (1 + 1) 4 (2 · 2)
dos if anidados 3 3 (1 + 2) 3
diez if en fila 11 10 1024 (2102^{10})
diez if anidados 11 55 (1 + 2 + … + 10) 11

La ciclomática no distingue las dos formas. La cognitiva castiga el anidamiento. NPath castiga la secuencia y da menos a la forma anidada, porque tiene menos caminos: si la primera condición es falsa, las demás ni se evalúan. Las dos métricas que «van más allá» de McCabe lo hacen en direcciones opuestas.

Elige la ciclomática cuando la pregunta sea de tests: es el número de tests de la prueba estructurada de McCabe y una cota superior de los que hacen falta para cubrir todas las ramas. Elígela también para comparar con la literatura o con otra herramienta, sabiendo que cada herramienta cuenta &&, ||, catch y case a su manera. Su punto débil: un switch plano de veinte casos vale 21 y se lee de un vistazo.

Elige la cognitiva para decidir qué refactorizar pensando en quien va a leer el código. Un switch entero suma 1, una cadena de && iguales suma 1 y cada nivel de anidamiento encarece lo que hay dentro. Como un método vacío vale 0, la suma por clase distingue cien getters de un método enrevesado. Su punto débil: las reglas se fijaron por juicio, no a partir de un modelo, y no ven los datos ni los nombres.

Elige NPath cuando las decisiones de un método interactúan (una usa un valor que cambió otra) y quieras saber cuántas combinaciones quedan sin probar si solo cubres ramas. Crece tan deprisa que conviene leer su logaritmo, y su definición tiene fallos conocidos: no siempre cuenta los caminos acíclicos que dice contar. Tampoco mide la dificultad de lectura: veinte comprobaciones de null independientes valen más de un millón.

En la práctica, lee v(G) y CogC juntas. v(G) alta con CogC baja suele ser un switch plano o una lista de casos en fila; CogC mucho más alta que v(G) señala anidamiento. Si dispones de NPath, un valor muy superior a v(G) dice que el método encadena muchas decisiones en secuencia: candidato a partirse en pasos.

Ojo. No apliques el umbral de una a otra. Los tres números viven en escalas distintas y el mismo método puede estar bien en una y mal en otra.

Todas las métricas del aspecto

Las métricas que Stau Metro no calcula están marcadas con «no» en la última columna; tienen página porque son clásicas o se citan a menudo.

Familia de McCabe

Métrica Nivel Stau Metro Qué dice
«Complejidad ciclomática» (v(G)) método sí Decisiones más 1: los caminos independientes del método
«Complejidad ciclomática esencial» (ev(G)) método sí La parte de v(G) que no se deja estructurar: decisiones con salidas anticipadas o saltos
«Complejidad de diseño» (iv(G)) método sí La parte de v(G) que decide a qué otros métodos se llama
«Complejidad ciclomática promedio» (v(G)avg) paquete, módulo, proyecto sí Media de v(G) por método, con el mismo recuento
«Complejidad ciclomática total» (v(G)tot) paquete, módulo, proyecto sí Suma de v(G); crece con el tamaño

Más detalle sobre su origen en «Métricas de McCabe».

Complejidad por clase

Métrica Nivel Stau Metro Qué dice
«Complejidad ponderada de los métodos» (WMC) clase sí Suma de la complejidad de los métodos; la métrica de complejidad de «CK»
«Complejidad promedio de las operaciones» (OCavg) clase sí Complejidad media por método: el estilo de la clase
«Complejidad máxima de las operaciones» (OCmax) clase sí El método más complejo, que la media puede ocultar

Legibilidad y anidamiento

Métrica Nivel Stau Metro Qué dice
«Complejidad cognitiva» (CogC) método sí Rupturas del flujo lineal, con recargo por cada nivel de anidamiento
«Profundidad de anidamiento de bloques» (NBD) método sí Nivel máximo de bloques anidados: condiciones, bucles, try, lambdas
«Profundidad de anidamiento condicional» (IF_NEST) método sí El mismo máximo contando solo if; else if no añade nivel
«Profundidad de anidamiento de bucles» (LOOP_NEST) método sí El mismo máximo contando solo bucles

Caminos y otras medidas compuestas

Métrica Nivel Stau Metro Qué dice
«Complejidad NPath» (NPATH) método no Caminos acíclicos: las decisiones en secuencia se multiplican
«Métrica ABC» (ABC) método, clase, paquete no Vector de asignaciones, llamadas y condiciones; su autor la propuso como medida de tamaño

Medidas de Halstead

Métrica Nivel Stau Metro Qué dice
«Longitud» (N) método, clase sí Apariciones de operadores y operandos: tamaño en tokens
«Vocabulario» (n) método, clase sí Operadores y operandos distintos
«Volumen» (V) método, clase sí Tamaño en bits: longitud por el logaritmo del vocabulario
«Dificultad» (D) método, clase sí Densidad: muchos operadores distintos y operandos repetidos
«Esfuerzo» (E) método, clase sí Dificultad por volumen
«Errores estimados» (B) método, clase sí Defectos esperados según la fórmula de Halstead; no es un recuento real
«Tiempo de programación» (T) método, clase no El esfuerzo dividido entre 18, en «segundos»

Más detalle en «Medidas de Halstead».

Perfiles de criterios de calidad (QCP)

Métrica Nivel Stau Metro Qué dice
«QCP (corrección)» (QCP_CRCT) método sí Suma ponderada de D, sentencias de control, sentencias ejecutables y decisiones
«QCP (mantenibilidad)» (QCP_MAINT) método sí Ingredientes parecidos con la longitud de Halstead como término dominante
«QCP (fiabilidad)» (QCP_RLBTY) método sí Menos peso al tamaño y más a las decisiones y al anidamiento

Recuentos de sentencias y de la firma

Métrica Nivel Stau Metro Qué dice
«Número de parámetros» (NP) método sí Parámetros de la firma: lo difícil que es llamar bien al método
«Número promedio de parámetros» (OPavg) clase sí Media de NP sobre los métodos y constructores de la clase
«Número de sentencias de control» (CONTROL) método sí Sentencias que dirigen el flujo: condicionales, bucles, switch, try, saltos
«Densidad de control» (CDENS) método sí Qué proporción de las sentencias es de control
«Número de sentencias de bucle» (LOOP) método sí Bucles, anidados o en fila
«Número de sentencias de ramificación» (BRANCH) método sí break y continue que cortan bucles
«Número de puntos de retorno» (RETURN) método sí Por cuántos sitios puede salir el método
«Número de comprobaciones de null» (NULL) método sí Comparaciones con null: programación defensiva
«Número de expresiones de conversión de tipo» (CAST) método sí Moldes e instanceof
«Número de excepciones capturadas» (CAUGHT) método sí Tipos de excepción distintos en los catch
«Número de excepciones lanzadas» (THROWS) método sí Tipos de excepción declarados en throws
«Número de sentencias assert» (ASSERT) método sí Suposiciones que el método comprueba con assert

Cómo se combinan

Con el tamaño, siempre. Casi todas las medidas de complejidad tienden a crecer con la longitud del método. Shepperd (1988) ya concluyó que en muchos conjuntos de datos la complejidad ciclomática aporta poco más que las líneas de código. Antes de concluir que un método es complejo y no solo largo, compáralo con las «líneas de código sin comentarios» (NCLOC); la «guía de tamaño» cuenta el resto.

Anidamiento: máximo y coste. NBD dice hasta dónde baja el punto más hondo; CogC suma el coste de cada nivel en cada estructura. Con NBD alta y CogC moderada, el problema es puntual. IF_NEST y LOOP_NEST dicen de qué está hecha la profundidad: muchos bucles anidados avisan además de recorridos que se multiplican.

Estructura y legibilidad tiran en sentidos opuestos. Las cláusulas de guarda (if (x == null) return;) suben la «complejidad esencial» y los «puntos de retorno», pero bajan NBD y CogC. Si un cambio baja ev(G) a costa de subir el anidamiento, lo normal es que haya empeorado la lectura.

Del método a la clase y al paquete. WMC, OCavg y OCmax llevan la complejidad a la clase; v(G)avg y v(G)tot, al paquete, el módulo y el proyecto. Lee siempre la media con el máximo: la distribución por método es muy asimétrica y pocos métodos concentran casi toda la complejidad. En Stau Metro, WMC, OCavg y OCmax usan un recuento que no incluye &&, || ni catch, mientras que v(G)avg y v(G)tot usan el mismo que v(G); por eso la suma de los WMC de un paquete no coincide con su v(G)tot. Las trampas generales de agregar están en «Agregar métricas».

Decisiones frente a datos. Las medidas de McCabe y la cognitiva cuentan decisiones; las de Halstead cuentan operadores y operandos, y por eso ven la complejidad de las expresiones que las otras no ven. V es sobre todo tamaño; D es densidad. El «índice de mantenibilidad» combina V, v(G) y las líneas de código en una sola cifra.

Las puntuaciones compuestas, para ordenar. Las tres QCP suman ingredientes en escalas distintas con pesos sin justificación publicada, y no se ha encontrado ningún estudio que las valide. Sirven para ordenar los métodos de un proyecto; ante un valor alto, mira qué término lo empuja. Lo mismo vale para B de Halstead, que es una estimación y no un recuento de defectos.

Los recuentos sueltos, para diagnosticar. CONTROL, CDENS, LOOP, BRANCH, RETURN, NULL, CAST, CAUGHT, THROWS y ASSERT son informativos: no tienen umbral en Stau Metro y no son buenos ni malos por sí mismos. Sirven para explicar de dónde sale una v(G) o una CogC alta: si son comprobaciones de null defensivas, si son conversiones de tipo, si son saltos dentro de bucles.

La firma, aparte. NP no mide el cuerpo del método sino lo que pide quien lo llama. Un método con muchos parámetros suele tener también muchas decisiones; los dos valores altos a la vez señalan un método que hace demasiado.

Qué no miden

  • Si el código es fácil de entender. Scalabrino y otros (2021) midieron 121 métricas, entre ellas las líneas de código y la complejidad ciclomática, frente a 444 evaluaciones de comprensión hechas por 63 desarrolladores: ninguna llegó a una correlación media o fuerte con la comprensión, ni con la percibida ni con la real; las pocas que se correlacionaron lo hicieron débilmente, y combinarlas en modelos mejoró poco. La complejidad cognitiva no estaba en ese estudio; Muñoz Barón, Wyrich y Wagner (2020) sí encontraron correlación con el tiempo de comprensión y con la dificultad percibida, con resultados mixtos en otros indicadores (ver su «página»).
  • Los nombres y el vocabulario del dominio. Un método plano con variables mal nombradas o con llamadas a una API desconocida puede ser muy difícil de leer y puntuar bajo en todo. En un estudio con resonancia magnética funcional, Peitek y otros (2021) encontraron que las métricas de complejidad explican la cognición de quien programa solo de forma limitada, y que el tamaño textual del código atrae la atención mientras que el tamaño del vocabulario carga la memoria de trabajo.
  • La complejidad repartida entre métodos. Extraer métodos baja todas las métricas de método sin que la lógica global cambie. La complejidad que vive en las relaciones entre clases es asunto del «acoplamiento».
  • Los datos y el estado. Ninguna métrica del aspecto ve el estado mutable compartido, la concurrencia o lo complicado de una estructura de datos. Halstead mira operandos, pero no su significado.
  • La corrección. Una complejidad baja no dice que el código funcione, ni una alta que falle. Para eso están los «tests» y la evolución de los defectos; la «evidencia empírica» sobre la relación entre complejidad y defectos tiene su propia página.

Los umbrales de aviso de Stau Metro en este aspecto (por encima de 10 para v(G), 15 para CogC, 3 para NBD, 5 para NP, 31 para WMC y 3,1 para OCavg) y el 200 habitual de NPath tienen procedencias distintas, que cada página de métrica indica; cómo se fijan en general se explica en «De dónde salen los umbrales». Qué cuenta cada herramienta, y por qué no dan el mismo número para el mismo método, está en «Herramientas».

Referencias

  • McCabe, T. J. (1976). «A Complexity Measure». IEEE Transactions on Software Engineering, SE-2(4), 308-320. https://ieeexplore.ieee.org/document/1702388
  • Halstead, M. H. (1977). Elements of Software Science. Elsevier North-Holland.
  • Nejmeh, B. A. (1988). «NPATH: A Measure of Execution Path Complexity and Its Applications». Communications of the ACM, 31(2), 188-200. https://doi.org/10.1145/42372.42379
  • Shepperd, M. (1988). «A Critique of Cyclomatic Complexity as a Software Metric». Software Engineering Journal, 3(2), 30-36.
  • Fitzpatrick, J. (1997). «Applying the ABC Metric to C, C++, and Java». C++ Report, junio de 1997.
  • Campbell, G. A. Cognitive Complexity: a new way of measuring understandability. Informe técnico de SonarSource, versión 1.7, 2023. https://www.sonarsource.com/docs/CognitiveComplexity.pdf
  • Bagnara, R., Bagnara, A., Benedetti, A. y Hill, P. M. (2016). «The ACPATH Metric: Precise Estimation of the Number of Acyclic Paths in C-like Languages». arXiv:1610.07914. https://arxiv.org/abs/1610.07914
  • 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 ESEM 2020. https://arxiv.org/abs/2007.12520
  • Scalabrino, S., Bavota, G., Vendome, C., Linares-Vásquez, M., Poshyvanyk, D. y Oliveto, R. (2021). «Automatically Assessing Code Understandability». IEEE Transactions on Software Engineering, 47(3), 595-613. https://doi.org/10.1109/TSE.2019.2901468
  • Peitek, N., Apel, S., Parnin, C., Brechmann, A. y Siegmund, J. (2021). «Program Comprehension and Code Complexity Metrics: An fMRI Study». Proceedings of the 43rd International Conference on Software Engineering (ICSE 2021), 524-536. https://doi.org/10.1109/ICSE43902.2021.00056