Técnicas de refactorización de código para equipos

Tienes un módulo que nadie quiere tocar. Los bugs se acumulan allí. Cada PR que lo roza tarda el doble en revisarse. Tres ingenieros de tu equipo lo han llamado, por separado, "el ala maldita". Sabes que necesita refactorización, pero también sabes que el último que lo intentó desapareció durante dos sprints y salió con un feature flag roto y una expresión levemente derrotada.

Las técnicas de refactorización de código existen en un espectro que va desde "renombrar la variable" hasta "reestructurar todo el límite del servicio". Esta guía cubre las que realmente mueven métricas: tiempo hasta el primer commit de ingenieros nuevos, tasa de bugs por módulo, y duración de revisiones de PRs.

Extract Method: la refactorización que puedes hacer hoy mismo

Si solo puedes aplicar una técnica a una codebase, es Extract Method. Identificas un bloque de código dentro de una función larga que hace una sola cosa coherente, lo extraes en una función con nombre, y obtienes dos beneficios inmediatos: la función padre se vuelve legible, y la función extraída se puede testear de forma aislada.

La regla que uso: si tienes que escribir un comentario para explicar qué hace un bloque de código, ese bloque debería ser una función en su lugar. El nombre de la función se convierte en el comentario, y a diferencia de los comentarios, los nombres de función rompen el build cuando quedan desactualizados.

Esta técnica también tiene un beneficio colateral: cuando la función extraída es pequeña y tiene un nombre claro, el revisor puede validarla sin leer el contexto completo. Eso acorta el tiempo de revisión en PRs que tocan código legacy.

Reemplazar condicional con polimorfismo

Las cadenas largas de if/elif/else o los switch que comprueban un campo de tipo son uno de los patrones que más dificultan la extensión del código. La solución es reemplazar el condicional con una jerarquía de clases o un patrón estrategia. Cada caso se convierte en su propia clase con la misma interfaz.

Salta esta técnica si tu condicional tiene dos ramas y no va a crecer. El polimorfismo tiene un coste: ahora tienes múltiples archivos donde antes había una función. El ROI solo aparece a escala.

Cuando el equipo de un ecommerce español que conozco migró su motor de descuentos de un if-elif de 400 líneas a clases de estrategia, el tiempo de añadir un nuevo tipo de descuento bajó de dos días a dos horas. El cambio no fue gratuito: llevó tres sprints hacerlo bien. Pero la deuda técnica acumulada justificaba la inversión.

Análisis de hotspots: dónde refactorizar primero

Combina complejidad ciclomática con frecuencia de cambios. Un módulo puede ser genuinamente terrible pero estar sin tocar durante tres años. Refactorizarlo es arqueología, no ingeniería. Los módulos que te custan son los que están sucios Y en los que tu equipo entra cada semana.

El proceso es concreto:

1. Calcula la complejidad ciclomática de cada archivo (herramientas como radon en Python o complexity-report en JS lo hacen en minutos).

2. Extrae la frecuencia de cambios con git log --format="%H" -- <archivo> | wc -l para cada archivo del repo.

3. Construye una matriz: complejidad en eje X, frecuencia de cambios en eje Y. Los archivos en el cuadrante superior derecho son tus hotspots reales.

BCG reportó en 2024 un ROI 3 veces mayor en refactorización sistemática comparada con la ad-hoc. La diferencia está en priorizar con datos, no con intuición.

Branch-by-Abstraction: refactorizar sistemas en producción

Crea una abstracción que envuelva la implementación actual, mueve los llamadores a usar la abstracción, escribe la nueva implementación detrás de ella, luego haz el switch. Así es como funciona el patrón strangler fig a nivel de servicio.

La secuencia exacta:

1. Introduce una interfaz (o clase abstracta) que el código existente ya implementa de facto.

2. Haz que todos los callers usen esa interfaz.

3. Escribe la nueva implementación detrás de la abstracción.

4. Cambia el punto de inyección. Borra la implementación vieja.

Esto funciona porque en ningún momento el sistema queda roto. Puedes hacer commit después de cada paso. Puedes hacer el switch en producción con un feature flag si necesitas validar antes de borrar.

Reemplazar número mágico con constante con nombre

Las constantes con nombre no son una preferencia de estilo. Son un mecanismo de fuente única de verdad. Cuando la constante cambia, cambia en todos los sitios automáticamente.

El error más común en equipos hispanoablantes: usar constantes en Python o JS pero seguir usando literales en las queries SQL o en los ficheros de configuración. La consistencia tiene que ser total, o la ventaja desaparece.

# Mal
if intentos > 3:
    bloquear_cuenta()

# Bien
MAX_INTENTOS_LOGIN = 3

if intentos > MAX_INTENTOS_LOGIN:
    bloquear_cuenta()

Cuando el límite de reintentos cambia de 3 a 5, cambias una línea. Sin buscar en el repo, sin grep desesperado, sin el bug que alguien se dejó en el worker que no vio.

Introduce Parameter Object

Una función que acepta seis argumentos es una función que alguien va a llamar mal. Cuando un grupo de parámetros siempre viajan juntos, pertenecen a un objeto.

# Antes
def crear_pedido(cliente_id, producto_id, cantidad, descuento, direccion, metodo_pago):
    ...

# Después
@dataclass
class PedidoRequest:
    cliente_id: int
    producto_id: int
    cantidad: int
    descuento: float
    direccion: str
    metodo_pago: str

def crear_pedido(pedido: PedidoRequest):
    ...

El beneficio no es solo legibilidad. Es que ahora puedes validar PedidoRequest en su constructor, pasar el objeto completo a través de capas sin reescribir firmas, y extender los parámetros sin romper todos los callers existentes.

La mentalidad de refactorización preparatoria

Refactoriza justo antes de añadir una funcionalidad, no como un proyecto independiente. Kent Beck lo formuló así: "Haz el cambio fácil, luego haz el cambio fácil." El equipo de gestión no necesita aprobar una iniciativa de refactorización cuando está embebida en trabajo de funcionalidades.

En la práctica: cuando abres un ticket de feature, antes de escribir la primera línea nueva, dedica 30-60 minutos a dejar el módulo en mejor estado del que estaba. Extract Method en las funciones que vas a modificar. Renombra las variables ambiguas. Añade el test que falta. Luego implementa.

McKinsey 2024 reporta un 40-50% de reducción en tiempo de entrega con modernización sistemática. La clave es "sistemática": no dos sprints de refactorización seguidos de ocho de deuda acumulada, sino refactorización preparatoria integrada en cada ticket.

El Stack Overflow Developer Survey recoge que el 62% de los desarrolladores se siente frustrado por la deuda técnica. La diferencia entre ese 62% y el resto no es el tiempo disponible, es si la refactorización está dentro o fuera del flujo de trabajo habitual.

Lo que las herramientas de IA hacen (y no hacen) en refactorización

Cursor, GitHub Copilot y Cody reducen la fricción en refactorización mecánica. Ejecutan Extract Method, renombran símbolos en todo el proyecto, generan tests para código extraído. Eso es real y útil.

Lo que no hacen: no te dicen dónde refactorizar. No razonan sobre tendencias de complejidad. No saben qué archivos modifica tu equipo más frecuentemente. No conocen el contexto de negocio que hace que un módulo sea un hotspot.

La capa estratégica sigue siendo un juicio humano. Las herramientas de IA aceleran la ejecución una vez que has tomado la decisión. Si intentas que decidan por ti qué refactorizar, obtendrás refactorizaciones localmente correctas pero estratégicamente irrelevantes.

Por dónde empezar el lunes

Ejecuta el análisis de hotspots en tu repo esta semana. Elige el archivo con mayor puntuación. Aplica Extract Method a las tres funciones más largas. Escribe los tests. Haz commit con un mensaje que referencie el score de complejidad del que partiste.

No necesitas un sprint de refactorización. Necesitas que la refactorización preparatoria se convierta en un hábito de equipo. La diferencia entre una codebase que mejora y una que se deteriora no es el tiempo, es si el equipo deja el código mejor del que lo encontró en cada PR.

FAQ

¿Cuál es la diferencia entre refactorización y reescritura?

Refactorización cambia la estructura interna del código sin alterar su comportamiento observable. Reescritura construye funcionalidad nueva desde cero. La refactorización se puede hacer de forma incremental y segura con tests. La reescritura es un proyecto con riesgo propio. La mayoría de las veces, la refactorización incremental es la opción correcta.

¿Cuándo tiene sentido refactorizar sin un ticket de feature?

Cuando el módulo es un hotspot confirmado (alta complejidad + alta frecuencia de cambios) y el coste de no refactorizarlo supera el coste de hacerlo ahora. Ese análisis requiere datos del repo, no intuición. Si no tienes los datos, empieza por recogerlos.

¿Cómo justifico tiempo de refactorización a gestión?

No pidas tiempo de refactorización. Incrústala en el trabajo de feature con la mentalidad preparatoria de Kent Beck. La conversación cambia de "necesito dos sprints para limpiar código" a "este ticket lleva tres horas más porque lo dejo en mejor estado para el siguiente".

¿Extract Method tiene límites?

Sí. No aplica Extract Method a código que es genuinamente lineal y secuencial donde la legibilidad mejora con la secuencia visible. Un script de migración de datos que hace diez pasos en orden puede ser más legible como una función larga bien comentada que como diez funciones pequeñas.

¿Las herramientas de IA pueden hacer el análisis de hotspots?

Ninguna herramienta de IA tiene acceso nativo a tu historial de git ni a tus métricas de complejidad por defecto. Puedes extraer esos datos tú mismo y dárselos como contexto, pero el análisis de hotspots requiere datos específicos de tu repo que la IA no tiene sin que se los proporciones explícitamente.

¿Cuánto tiempo lleva ver resultados de refactorización sistemática?

En equipos que aplican refactorización preparatoria consistentemente, los primeros efectos son visibles en 4-6 semanas: menos contexto necesario para revisar PRs, menos bugs en módulos refactorizados. El impacto en tasa de bugs por módulo tarda uno o dos trimestres en ser estadísticamente significativo.

¿Cuál es el orden correcto de las técnicas?

No hay un orden universal. El análisis de hotspots te dice dónde. Extract Method suele ser el primer movimiento dentro de un módulo porque crea las unidades testeables que permiten aplicar técnicas más avanzadas de forma segura.