Higiene de Cambio y Artesanía de Código
Resumen
Cómo se dan forma a los cambios y cómo se escribe código. Dos temas: separar el cambio estructural del cambio de comportamiento, y decir lo que quieres decir con la menor complejidad que funcione.
Higiene de Cambio
- Cambios estructurales antes que cambios de comportamiento, validados de forma independiente. Reorganizar (dividir archivos, renombrar, añadir comentarios) es un paso separado y verificable de forma independiente de cambiar el comportamiento (nuevas restricciones, lógica alterada). Nunca los mezcles en un solo cambio indivisible: un revisor no puede distinguir una reorganización segura de cambios de lógica reales.
- Un solo propósito por cambio. Un cambio tiene un único propósito enunciable.
- Mejora el código en el que trabajas cuando sus problemas afectan tu tarea (deja el campamento más limpio) — pero no comiences una refactorización no relacionada. Mantente enfocado en el objetivo.
Artesanía de Código
- Explícito sobre implícito. Sin comodines donde corresponden nombres, sin conversiones implícitas, sin cadenas vacías ni centinelas mágicos. Di lo que quieres decir.
- Nombres descriptivos. Las funciones/variables describen lo que hacen; sigue los modismos del lenguaje y el ecosistema.
- Comenta la intención, no el mecanismo. Explica por qué cuando no sea obvio; omite comentarios sobre código evidente.
- Unidades pequeñas y de un solo propósito. Para cualquier unidad deberías poder indicar qué hace, cómo usarla, de qué depende — sin leer sus internos. Un archivo grande generalmente está haciendo demasiado.
- DRY en código de producción, con criterio. La duplicación es una señal, no un error automático. La segunda ocurrencia casi idéntica desencadena una decisión deliberada: abstraer, o registrar por qué no. Abstrae el significado compartido, nunca la forma coincidente — las cosas que se parecen pero cambian por razones diferentes se mantienen separadas.
- Sigue los estándares del ecosistema. Usa los modismos y las bibliotecas bien soportadas que un profesional competente espera. No reinventes lo que la plataforma ya resolvió.
Las Tensiones Nombradas
- DRY vs. abstracción prematura: el código de producción abstrae sobre repetición demostrada de intención, no sobre repetición anticipada de forma. Cuando no estés seguro, espera a la tercera ocurrencia (YAGNI gobierna el desempate).
- DRY vs. DAMP: el código de producción es DRY; el código de prueba es DAMP (claridad sobre des-duplicación, ver
pruebas-como-control). Aplicar DRY a las pruebas es una violación.
Racionalizaciones Comunes
| Excusa | Realidad |
|---|---|
| "Renombraré y añadiré la funcionalidad en un solo commit" | Estructura y comportamiento en un solo diff no son revisables. Divídelos. |
| "Dos copias, debo aplicar DRY ahora" | Segunda ocurrencia = decidir. Misma forma ≠ mismo significado. La duplicación coincidente debe mantenerse separada. |
| "Ya que estoy aquí, déjame refactorizar este otro módulo" | La refactorización no relacionada amplía el alcance y el riesgo. Anótalo; no lo hagas ahora. |
| "Una línea ingeniosa es más elegante" | Lo explícito vence a lo ingenioso. Optimiza para el próximo lector. |
Señales de Alerta — DETENTE
- Un diff que mueve código y cambia su comportamiento
- Un PR cuyo propósito necesita la palabra "y" para describirse
- Abstraer ante la primera señal de similitud, o ante repetición anticipada (no real)
- Un archivo que ya no puedes mantener en tu cabeza
Razonamiento completo: Artículos V y VI de la constitución, agrupados en engineering-constitution/references/engineering-constitution.md.