Mantenibilidad
El código se lee con mucha más frecuencia de la que se escribe. La mantenibilidad es lo que separa un código base de 3 años que es un placer de uno que es un pozo de brea. Optimiza para el próximo desarrollador, que podrías ser tú en seis meses.
Reglas
- Una característica, un lugar. Empaqueta por funcionalidad (consulta backend/core/SKILL.md). Un cambio único debería afectar archivos adyacentes, no capas dispersas.
- Interfaces solo en los límites del módulo. Dentro de una funcionalidad, las clases concretas están bien. Las interfaces existen para que los llamadores dependan de contratos a través de los límites, no para decorar cada clase.
- Elimina, no comentes. El código muerto y los comentarios
// TODOeternos se pudren. Git recuerda; el IDE no necesita hacerlo. - Prefiere funciones pequeñas y puras. Más fáciles de probar, más fáciles de razonar, más fáciles de componer. Efectos secundarios en los bordes del sistema, no dispersos a lo largo de él.
- Las pruebas cubren el comportamiento, no la implementación. Reescribir el interior no debería romper las pruebas. Si lo hace, la prueba está acoplada a lo incorrecto.
- Las API públicas tienen versiones. Los cambios importantes detrás de una nueva versión o una bandera de funcionalidad, nunca un cambio de nombre silencioso.
- Inyección de dependencias por encima de singletons estáticos. Los estáticos no se pueden probar y ocultan el acoplamiento. Pasa las dependencias; moféalas en las pruebas.
- Fija y actualiza las dependencias regularmente. Archivos de bloqueo confirmados; Renovate/Dependabot haciendo PR automáticos. Quedarse 2 años atrás significa una migración no planificada de 2 semanas.
- Documenta el "por qué", no el "qué". El código muestra qué; los comentarios explican la regla de negocio, la restricción histórica, la compensación no obvia.
- Lintea, formatea y verifica tipos en CI. No es opcional, es bloqueante. Los humanos deberían debatir el diseño, no la colocación de espacios.
- Mantén la build verde y rápida. Las pruebas lentas o inestables se ignoran, y una vez ignoradas, no protegen nada.
Banderas rojas
- Un solo archivo de más de ~500 líneas, o una clase con más de ~10 métodos públicos — generalmente una funcionalidad intentando escapar.
- Paquete "utils" compartido donde los ayudantes huérfanos van a morir.
- Burlarse de lo que se está probando para que una prueba pase.
- "No toques ese módulo, ya nadie lo entiende."
- Tiempo de build de CI medido en decenas de minutos.