Cómo evaluar una refactorización PHP con métricas de mantenibilidad comprobables

Una refactorización puede reducir duplicación y, aun así, dificultar los cambios si añade abstracciones confusas o desplaza la complejidad a otra parte. Para evaluar su resultado, no basta con comparar una puntuación ni con comprobar que los tests pasan: hay que definir qué se quiere mejorar, observar varias señales y revisar si el sistema resulta más fácil de cambiar.

Esta guía explica cómo medir la mantenibilidad de una aplicación PHP antes y después de refactorizar, sin convertir las métricas en objetivos aislados. El método sirve para una clase, un módulo o un flujo de negocio, siempre que se compare el mismo alcance y se registre el contexto.

Por qué una métrica aislada no demuestra mantenibilidad

La mantenibilidad es la capacidad de comprender, probar y modificar un sistema con un riesgo razonable. Ningún indicador representa por sí solo esas capacidades. Menos líneas no significa necesariamente menos complejidad; más cobertura no garantiza tests útiles; y una puntuación estática favorable no revela si el equipo entiende el diseño.

Además, las métricas pueden cambiar por razones ajenas a la refactorización: una herramienta actualizada, reglas de análisis distintas, cambios en el alcance o código generado que se incorpora al informe. Por eso, una cifra debe interpretarse junto con su método de cálculo, el área analizada y las limitaciones conocidas.

El objetivo no es demostrar que el cambio “mejoró el código” en abstracto. Es comprobar si resolvió un problema concreto sin introducir riesgos desproporcionados.

Definir qué capacidad de cambio se quiere mejorar

Antes de medir, formula una hipótesis verificable y acotada. Por ejemplo: “Separar las reglas de cálculo de esta clase debería permitir probarlas sin iniciar el flujo HTTP” o “Reducir las dependencias de este servicio debería limitar los cambios necesarios para añadir una regla”. La hipótesis identifica un resultado esperado, no prescribe una arquitectura por moda.

Delimita el área y las operaciones afectadas: clases, endpoints, comandos, jobs o reglas de negocio. Anota también qué queda fuera, como una integración externa o una deuda conocida que no se abordará. Sin ese alcance, una comparación puede mezclar el efecto de la refactorización con otros cambios.

Conviene traducir la hipótesis a observaciones prácticas. ¿Debería ser más sencillo localizar la regla? ¿Se podrá probar sin una base de datos real? ¿Disminuirá el número de módulos que hay que modificar para un cambio habitual? Escoge pocas preguntas que el equipo pueda contestar con evidencia.

Establecer una línea base antes de cambiar el código

Registra el estado inicial en una revisión identificable del repositorio, con las mismas herramientas y configuración que usarás después. Para un área PHP, puede ser útil combinar estas señales:

• Complejidad: revisa métodos extensos, ramas condicionales y puntos donde se acumulan decisiones. La complejidad ciclomática puede orientar, pero no describe por sí sola la dificultad de comprender una regla.
• Acoplamiento: identifica dependencias directas, responsabilidades mezcladas y conexiones con infraestructura. Observa si una modificación obliga a conocer o tocar componentes no relacionados.
• Duplicación: localiza lógica repetida, distinguiendo duplicación accidental de reglas parecidas que deben evolucionar por separado.
• Pruebas: registra qué comportamientos importantes están cubiertos, qué pruebas son fiables y qué dependencias hacen que una prueba requiera servicios externos.
• Operación y entrega: anota fallos de producción o regresiones relevantes, dificultad para desplegar el cambio y pasos manuales asociados, si guardan relación con el área.

Si usas análisis estático, conserva el nombre de la herramienta, las reglas, la versión y el comando. El número sin esa información no es reproducible. También separa el código generado o externo cuando la configuración lo permita y deja constancia de las exclusiones.

Elegir indicadores verificables y registrar sus límites

Selecciona indicadores que respondan a la hipótesis. Para una refactorización orientada a aislar lógica, podrían servir el número de dependencias necesarias para probarla, la presencia de pruebas de comportamiento relevantes y el tiempo que tarda una persona del equipo en localizar el punto de cambio. Para reducir acoplamiento, puede observarse cuántos componentes deben modificarse en una tarea representativa.

No conviertas tiempos o recuentos en verdades universales: el tamaño de la tarea, la experiencia de quien la realiza y las interrupciones influyen. Si se usan, registra esas condiciones y trata el resultado como una señal, no como una comparación de productividad entre personas.

Documenta cada indicador con cuatro datos: qué mide, cómo se obtiene, qué resultado se esperaba y qué no puede demostrar. Por ejemplo, un recuento de dependencias puede mostrar una reducción, pero no prueba que las nuevas abstracciones sean fáciles de entender. La revisión técnica debe comprobarlo.

Comparar antes y después con el mismo método

Tras la refactorización, repite el análisis sobre el mismo alcance, con la misma configuración y, en lo posible, en condiciones equivalentes. Separa los cambios funcionales de los estructurales en la revisión. Si se modificaron ambos a la vez, identifica qué evidencia corresponde a cada uno y evita atribuir todo el resultado a la refactorización.

Además de las métricas, prueba un cambio real o representativo: corregir una regla, añadir una condición de negocio o adaptar una integración. Comprueba qué archivos hubo que modificar, qué pruebas fueron necesarias y dónde aparecieron dudas. No hace falta crear una tarea artificial si ya existe trabajo comparable; sí hace falta evitar presentar una impresión anecdótica como resultado concluyente.

Una mejora consistente combina señales: por ejemplo, menos dependencias para probar una regla, pruebas más enfocadas y una ruta de cambio que el equipo puede explicar. Si baja la complejidad de un método, pero crece la dispersión de la lógica o se vuelve más difícil seguir el flujo, el balance requiere revisión.

Combinar mediciones con revisión y feedback del equipo

La revisión técnica debe preguntar si las responsabilidades están más claras, si los nombres reflejan el dominio y si las nuevas interfaces resuelven una necesidad real. También debe buscar riesgos introducidos: contratos duplicados, dependencias invertidas de forma confusa, cambios de comportamiento accidentales o una nueva capa que solo reenvía llamadas.

El feedback del equipo aporta evidencia sobre comprensión y operación. Pregunta si resulta más fácil localizar la regla, escribir una prueba o estimar el alcance de un cambio. Vincula las respuestas a ejemplos concretos y registra desacuerdos: una arquitectura puede ser clara para quien la creó y opaca para quien mantiene el sistema.

En PHP, valida asimismo que la refactorización respete los contratos existentes: tipos, excepciones, efectos secundarios, serialización y comportamiento observable de las APIs. Un diseño interno más ordenado no compensa una regresión funcional o una incompatibilidad no prevista.

Errores habituales al medir mantenibilidad

• Perseguir cobertura: aumentar el porcentaje puede añadir pruebas superficiales. Evalúa si se prueban comportamientos y casos de riesgo, no solo si se ejecutan líneas.
• Premiar menos líneas: compactar código puede ocultar decisiones y hacer más difícil revisar cambios. El tamaño no es una medida directa de claridad.
• Optimizar una puntuación: adaptar el código a una herramienta puede dejar intacto el problema de diseño. Investiga qué significa el cambio y confirma su efecto en una tarea real.
• Comparar alcances distintos: mezclar archivos nuevos, código excluido o reglas cambiadas invalida la lectura. Mantén estable el método o explica las diferencias.
• Ignorar el comportamiento: una refactorización debe preservar el comportamiento esperado, salvo que el cambio funcional esté definido y validado por separado.

Plantilla breve para decidir cómo continuar

Al cerrar la evaluación, registra:

• Área y objetivo: qué parte se refactorizó y qué capacidad de cambio se buscaba mejorar.
• Línea base y método: revisión del código, herramientas, configuración, alcance y exclusiones.
• Señales observadas: resultados antes y después, más límites de cada indicador.
• Validación práctica: pruebas, revisión técnica y evidencia de un cambio representativo.
• Riesgos pendientes: comportamiento no cubierto, deuda aplazada y efectos operativos por comprobar.
• Decisión: continuar si la hipótesis se sostiene y los riesgos son aceptables; ajustar si hay señales mixtas o un problema de comprensión; detener si el coste o el riesgo supera el beneficio esperado.

La pregunta final no es si el código tiene una puntuación mejor, sino si el equipo puede modificar esa parte con más claridad y control. Una línea base reproducible, varias señales complementarias y una revisión honesta permiten tomar esa decisión sin confundir actividad de refactorización con una mejora demostrada.