Todo proyecto empieza limpio. Entonces llega la prisa, el «después lo arreglo» y, seis meses más tarde, nadie encuentra dónde vive la regla de negocio —ni siquiera quien la escribió.
La carpeta cuenta una historia (o debería)
Abre la raíz de un proyecto y ya deberías entender de qué trata solo por su estructura. Si las carpetas principales son utils, helpers, services y components, no has aprendido nada sobre el dominio: has aprendido sobre el framework, que es la parte menos importante.
Prefiere una estructura que refleje el negocio: checkout, facturacion, catalogo, usuarios. La capa técnica es un detalle dentro de cada una. Una persona nueva en el equipo debería poder señalar «la regla de descuento está aquí» sin abrir diez archivos para descubrirla.
Separación de responsabilidades sin terrorismo
La separación de responsabilidades se convirtió en una excusa para crear diez capas y un montón de interfaces que nadie entiende. No se trata de eso. Es simple: cada parte del código tiene una razón para existir y, preferiblemente, una sola razón para cambiar.
La prueba práctica es el commit. Si modificar una regla de precios te obliga a editar el componente de UI, el controller, un util y un enum, esas cosas no están separadas: están dispersas, que es lo contrario. Junta lo que cambia junto y aísla lo que cambia por razones diferentes.
Un buen nombre es el que no necesitas explicar
El nombre revela la intención. processData() no dice nada: ¿procesa qué y para qué? calcularEnvio() ya cuenta toda la historia antes de que abras el cuerpo de la función.
No ahorres letras. usr, tmp, d y flag2 cuestan caro cada vez que alguien vuelve a leerlos —y el código se lee mucho más de lo que se escribe—. Si necesitas un comentario para explicar qué guarda una variable, su nombre ya falló. Invierte esos segundos extra en escribir pedidosPendientes en lugar de arr.
Un archivo grande es deuda escondida
Un archivo de 800 líneas casi nunca hace una sola cosa. Empezó haciéndola, fue creciendo y terminó convertido en un depósito de «no sé dónde ponerlo, así que déjalo aquí».
Divide por responsabilidad, no por un número mágico de líneas. La mejor medida es cognitiva: un archivo debería caber en tu cabeza. Lo abres, entiendes qué hace y sales de ahí sin desplazarte por tres pantallas ni mantener cinco conceptos en la memoria al mismo tiempo. Cuando dudas cómo nombrar el archivo porque hace «varias cosas», esa es la señal de que en realidad son dos.
La colocación conjunta gana a las capas en la mayoría de los casos
Una regla que resuelve el 80 % de los casos: coloca juntos los elementos que cambian juntos. La prueba junto al código que prueba, el estilo junto al componente y el hook cerca de quien lo consume.
Separarlo todo por tipo técnico —un /tests gigante, un /styles gigante, un /hooks gigante— parece organizado en una captura de pantalla, pero en la práctica te obliga a abrir cuatro carpetas distantes para entender una sola funcionalidad. Y cuando eliminas la funcionalidad, queda basura repartida por todas ellas. La colocación conjunta también facilita la parte más honesta de todas: borrar.
El README no es un adorno
Un README que explica cómo ejecutar, cómo probar y dónde se encuentran las decisiones importantes ahorra horas a cada persona nueva —y a ti mismo dentro de tres meses, cuando lo hayas olvidado—.
Pero atención: una documentación que miente es peor que no tener documentación, porque confías en ella y tomas una decisión equivocada. La regla es tratar la documentación como código: si cambiaste el comando de build, cambia el README en el mismo commit. La documentación que vive lejos del código siempre se pudre.
La organización del código no es un adorno estético ni una obsesión de quien disfruta de las carpetas perfectamente alineadas. Es que el equipo encuentre las cosas rápido y cambie el sistema sin miedo. No necesitas refactorizar el mundo hoy: solo dejar un poco más claro el próximo archivo que toques.
