Entendiendo las Puntuaciones de Complejidad¶
¿Qué Significan los Números?¶
Las puntuaciones de complejidad cognitiva representan el esfuerzo mental requerido para entender un fragmento de código. Las puntuaciones más altas indican código más difícil de comprender y mantener.
Umbrales Recomendados¶
| Rango de Puntuación | Interpretación | Recomendación |
|---|---|---|
| 0-5 | Simple | Fácil de entender, no se requiere acción |
| 6-10 | Moderado | Generalmente aceptable, pero con vigilancia ante mayor crecimiento |
| 11-15 | Complejo | Considerar refactorización si se está añadiendo funcionalidad |
| 16-25 | Alto | Refactorización recomendada |
| 26+ | Muy Alto | Refactorización fuertemente recomendada |
Umbral Predeterminado
complexipy usa un umbral predeterminado de 15. Las funciones que superen esta puntuación activarán advertencias.
Cómo se Calcula la Complejidad¶
La complejidad cognitiva se calcula analizando el Árbol de Sintaxis Abstracta (AST) de tu código Python y aplicando estas reglas:
1. Incrementos de Complejidad Base¶
Cada estructura de flujo de control añade a la complejidad:
| Estructura | Puntuación | Ejemplo |
|---|---|---|
Sentencia if |
+1 | if condition: |
Cláusula elif |
+1 | elif other_condition: |
Cláusula else |
+1 | else: después de if, for, while o try (sin incremento por anidamiento; su cuerpo queda anidado) |
Bucle for |
+1 | for item in items: |
Bucle while |
+1 | while condition: |
Manejador except |
+1 | except ValueError: |
Cláusula finally |
+0 | finally: (su cuerpo no está anidado) |
| Operador ternario | +1 | x if condition else y |
| Cláusula de comprensión | +0 | [x for x in xs if x] |
2. Multiplicador de Anidamiento¶
Esta es la innovación clave: las estructuras anidadas añaden complejidad extra basada en su profundidad.
def example():
if a: # +1 (base)
if b: # +2 (1 base + 1 anidamiento)
if c: # +3 (1 base + 2 anidamiento)
pass
# Complejidad total: 6
La fórmula es: complexity = 1 + nesting_level
3. Operadores Booleanos¶
Las condiciones lógicas complejas aumentan la carga cognitiva:
# Puntuación: 3
def check(a, b, c):
if a and b or c: # +1 (if) +2 (operadores booleanos)
return True
- Cada secuencia de operadores iguales, leída de izquierda a derecha: +1
- Cada cambio entre
andyorinicia una nueva secuencia:a or b and c or dse leeor,and,ory suma +3
4. Casos Especiales¶
Break y Continue
# Puntuación: 3
for item in items: # +1
if condition: # +2 (1 + anidamiento)
break # +0 (sin puntuación adicional)
Sentencias Match (Python 3.10+)
# Puntuación: 5
match value: # +1
case 1:
if x: # +2 (1 + anidamiento)
pass
case 2:
if y: # +2 (1 + anidamiento)
pass
Recursión
Cada función en un ciclo de recursión añade +1 una sola vez, sin importar cuántas llamadas recursivas haga. El ciclo puede ser directo (fact llama a fact) o indirecto (a llama a b, b llama a a). El +1 de una función anidada, o de un método de una clase anidada en una función, va a la función que lo contiene. Una llamada cuenta cuando se resuelve en el mismo archivo: un nombre simple a cada def del ámbito de función o de módulo más cercano que lo enlaza, cuando todos los demás enlaces del nombre en ese ámbito (un parámetro, una asignación, un walrus, un destino de for o with, un nombre de except ... as, una captura de match, un del, un import, un alias de tipo o una clase) ya se ejecutaron siempre cuando ese def lo enlaza y ninguno se hace a través de una declaración global o nonlocal (el enlace está antes en el código, en otra rama del mismo if o match, o en un manejador except de un try cuyo cuerpo no ejecuta nada después del def, y en un bucle que repite a ambos se ejecuta antes en cada pasada: el def no está en un if u otro bloque propio dentro del bucle, ningún break ni continue queda entre ellos, ningún try o with rodea el bucle, y el enlace no está en la condición de un while), self.m() y cls.m() a un método de la clase de quien llama (una clausura dentro de un método usa el self de ese método), o K.m() a un método de la clase K cuando el nombre K se resuelve de la misma forma a exactamente una clase del archivo y todo otro enlace de K en ese ámbito siempre se ha ejecutado antes de que la clase enlace K, con la misma regla de orden que un def (un import con asterisco o un parámetro de tipo en ese ámbito, o un enlace hecho a través de una declaración global o nonlocal, deja la llamada sin resolver). Una llamada a través de K en los decoradores, las bases o el cuerpo de la propia clase K no se resuelve a ella, porque la clase aún no ha enlazado su nombre. Una llamada dentro de una lambda, o en los decoradores, los argumentos por defecto, las bases o el cuerpo de clase de una definición anidada, cuenta para la función que la contiene. Los parámetros propios de una lambda, las variables de bucle de una comprensión y los parámetros de tipo de una clase o función ocultan los nombres externos donde son visibles. Una llamada en el cuerpo de una clase a un nombre que el mismo cuerpo enlaza va al enlace del módulo cuando la llamada se ejecuta antes de ese enlace, y al enlace de la clase después; cuando el orden no se puede saber desde el código, como un enlace dentro de un if o de un bucle, la llamada no suma nada. Un decorador simple como @f no es una llamada, así que no cuenta. Las llamadas a través de super(), de otros objetos o de imports no cuentan, ni un método que K solo hereda, y los ciclos entre archivos no se detectan.
Decoradores
Una función cuyo cuerpo es solo un def anidado y un return no eleva el nivel de anidamiento de la función anidada, como indica la excepción de decoradores de Python del artículo. El return debe devolver la función anidada: por nombre (return inner), o como argumento directo de una llamada (return functools.wraps(f)(inner), return update_wrapper(inner, f)). Dos decisiones difieren del texto del artículo, que admite cualquier return y no nombra nada más. Una llamada a la función anidada, como return inner(), no cumple la condición: ejecuta la función anidada en lugar de devolverla, así que la función no es un decorador. Se permite un docstring inicial: documenta el decorador y no añade flujo de control. Cualquier otra sentencia elimina la excepción. Las expresiones del return siguen contando.
Construcciones de Python que el artículo no nombra
- Comprensiones: las cláusulas
foreifno suman nada y no elevan el nivel de anidamiento. El artículo ignora las abreviaturas que permiten escribir varias sentencias de forma legible como una sola, y una comprensión es una abreviatura de un bucle que construye un valor. Un ternario o un operador booleano dentro de una comprensión sigue contando. elseenfor,whileytry: +1, sin incremento por anidamiento, y su cuerpo eleva el nivel de anidamiento, comoelsedespués deif. El cuerpo delelsesolo se ejecuta cuando el bucle termina sinbreako cuando el cuerpo deltryno lanzó nada, así que es una rama que el lector debe seguir. El artículo llama aelseun incremento híbrido: sin incremento por anidamiento, pero con un nivel de anidamiento mayor para lo que contiene.- Guardas de
case: +0 por la guarda en sí. Una secuencia de operadores booleanos o un ternario dentro de ella cuenta, en el nivel de anidamiento delmatch. El artículo da un solo incremento a unswitchy a todos sus casos y no nombra las guardas, así que una guarda se lee como parte de su caso. - Operadores booleanos mezclados: los operadores de una condición se leen de izquierda a derecha, en el orden en que aparecen en el código, y cada cambio entre
andyorinicia una nueva secuencia. Unnotinicia una nueva condición para su operando.
Ejemplos Detallados¶
Ejemplo 1: Lógica Secuencial Simple¶
def process_user(user):
if not user: # +1
return None
if user.is_active: # +1
send_welcome_email()
if user.needs_verification: # +1
send_verification()
return user
# Complejidad total: 3
Análisis: Tres sentencias if secuenciales, sin anidamiento. Fácil de seguir.
Ejemplo 2: Lógica Anidada¶
def validate_order(order):
if order: # +1
if order.items: # +2 (1 + anidamiento)
for item in order.items: # +3 (1 + anidamiento)
if item.quantity > 0: # +4 (1 + anidamiento)
process(item)
return False
# Complejidad total: 10
Análisis: El anidamiento profundo crea un crecimiento exponencial en la carga cognitiva.
Ejemplo 3: Condiciones Complejas¶
def check_eligibility(user, product):
if user.age >= 18 and user.verified and product.available: # +2
# ^^^ if: +1, secuencia and: +1, total: +2
return True
return False
# Complejidad total: 2
Análisis: Múltiples operadores booleanos aumentan la carga mental para comprender la condición.
Ejemplo 4: Manejo de Excepciones¶
def load_config(path):
try: # try en sí mismo: +0
with open(path) as f: # +0 (with no suma nada y no anida)
data = json.load(f)
if validate(data): # +1 (los cuerpos de try y with no están anidados)
return data
except FileNotFoundError: # +1
create_default_config()
except json.JSONDecodeError: # +1
log_error()
finally: # +0 (finally en sí mismo)
if log_enabled: # +1
log("Config load attempted")
# Complejidad total: 4
Directrices Prácticas¶
¿Qué Debería Refactorizar?¶
Enfócate en las funciones con puntuaciones por encima de tu umbral (predeterminado: 15). Estrategias comunes de refactorización:
- Extraer Métodos - Mover la lógica anidada a funciones separadas
- Retornos Anticipados - Usar cláusulas de guarda para reducir el anidamiento
- Simplificar Condiciones - Dividir expresiones booleanas complejas en variables con nombre
- Patrón Estrategia - Reemplazar if/else anidados con polimorfismo
Ejemplo de Refactorización¶
Antes (Complejidad: 13)
def process_order(order):
if order: # +1
if order.is_valid(): # +2
if order.payment: # +3
if order.payment.process(): # +4
ship_order(order)
else: # +1 (cláusula else)
refund(order)
else: # +1 (cláusula else)
notify_payment_required()
else: # +1 (cláusula else)
log_invalid_order()
return False
Después (Complejidad: 4)
def process_order(order):
if not order: # +1
return False
if not order.is_valid(): # +1
log_invalid_order()
return False
if not order.payment: # +1
notify_payment_required()
return False
if order.payment.process(): # +1
ship_order(order)
return True
refund(order)
return False
Mejoras clave:
- Anidamiento reducido de 4 niveles a 1
- Complejidad reducida de 13 a 4
- La lógica ahora es lineal y más fácil de seguir
Consejos para Interpretar Puntuaciones¶
- El Contexto Importa - Una puntuación de 20 puede ser aceptable para un algoritmo complejo pero problemática para lógica de negocio
- Tendencia en el Tiempo - Observa la complejidad creciente en funciones que modificas frecuentemente
- Puntuaciones Relativas - Compara funciones dentro de la misma base de código para identificar valores atípicos
- Acuerdo del Equipo - Establece umbrales que funcionen para tu equipo y proyecto