Diseño de Código
Comunícate con el usuario en español. Los siguientes términos aparecen en inglés y español la primera vez que se mencionan; después, úsalos de acuerdo con esta tabla unificada.
Diseña módulos profundos (deep modules) : coloca mucha conducta detrás de una interfaz pequeña, sobre una costura limpia (seam), y que se pueda probar a través de esa interfaz. Siempre que diseñes o refactorices código, usa este lenguaje y estos principios. El objetivo es: dar apalancamiento (leverage) a los llamadores, dar localidad (locality) a los mantenedores, y hacer que todo sea fácil de probar para todos.
Glosario
Usa exactamente los siguientes términos: no los reemplaces por "componente", "servicio", "API" o "límite". El lenguaje consistente es el punto clave.
Módulo (Module) : cualquier cosa que tenga una interfaz y una implementación. Intencionadamente no tiene escala fija: puede ser una función, una clase, un paquete, o una rebanada que atraviese varias capas. Evita usar: unidad, componente, servicio.
Interfaz (Interface) : todo lo que un llamador debe saber para usar correctamente este módulo: la firma de tipos, así como invariantes, restricciones de orden de llamada, modos de error, configuración necesaria y características de rendimiento. Evita usar: API, firma (demasiado estrecha, se refiere solo a la superficie del tipo).
Implementación (Implementation) : lo que está dentro del módulo, es decir, su cuerpo de código. Diferente de Adaptador (Adapter) : algo puede ser un adaptador pequeño con mucha implementación (por ejemplo, un repositorio SQLite), o un adaptador grande con poca implementación (por ejemplo, un objeto falso en memoria). Usa "adaptador" cuando hables de costuras; "implementación" en los demás casos.
Profundidad (Depth) : el apalancamiento en la interfaz. Cuánta conducta puede usar un llamador (o una prueba) por cada unidad de interfaz que aprende. Un módulo que esconde mucha conducta detrás de una interfaz pequeña es profundo; un módulo cuya interfaz es casi tan compleja como su implementación es superficial.
Costura (Seam) (Michael Feathers): un lugar donde puedes cambiar el comportamiento sin modificar ese lugar; es decir, la ubicación donde está la interfaz del módulo. Dónde colocar la costura es una decisión de diseño en sí misma, separada de lo que se coloca detrás de esa costura. Evita usar: límite (confunde con el contexto delimitado de DDD).
Adaptador (Adapter) : algo concreto que satisface una interfaz en una costura determinada. Describe el rol (qué posición ocupa), no el contenido (qué hay dentro).
Apalancamiento (Leverage) : el beneficio que un llamador obtiene de la profundidad. Por cada unidad de interfaz que aprende, obtiene más capacidad. El valor de una implementación se recupera en N lugares de llamada y M pruebas.
Localidad (Locality) : el beneficio que un mantenedor obtiene de la profundidad. Las modificaciones, errores, conocimiento y validaciones se concentran en un solo lugar, no se dispersan entre los llamadores. Se arregla una vez; tiene efecto en todas partes.
Profundo vs. Superficial
Módulo profundo (Deep module) = interfaz pequeña + implementación grande:
┌─────────────────────┐
│ Interfaz pequeña │ ← pocos métodos, parámetros simples
├─────────────────────┤
│ │
│ Implementación │ ← lógica compleja escondida dentro
│ profunda │
└─────────────────────┘
Módulo superficial (Shallow module) = interfaz grande + implementación pequeña (evita):
┌─────────────────────────────────┐
│ Interfaz grande │ ← muchos métodos, parámetros complejos
├─────────────────────────────────┤
│ Implementación delgada │ ← solo pasa las cosas
└─────────────────────────────────┘
Al diseñar la interfaz, pregúntate:
- ¿Puedo reducir el número de métodos?
- ¿Puedo simplificar los parámetros?
- ¿Puedo esconder más complejidad dentro?
Principios
- La profundidad es una propiedad de la interfaz, no de la implementación. Un módulo profundo puede estar compuesto internamente por piezas pequeñas, simulables (mockeables) y reemplazables; pero esas piezas no pertenecen a la interfaz. Un módulo puede tener costuras internas (implementación privada, para sus propias pruebas) y costuras externas (en la interfaz).
- Prueba de eliminación. Imagina que eliminas este módulo. Si la complejidad desaparece, solo era un mensajero. Si la complejidad reaparece en N lugares de llamada, entonces está haciendo su trabajo.
- La interfaz es la superficie de prueba. Los llamadores y las pruebas cruzan la misma costura. Si intentas probar a través de la interfaz, la forma del módulo probablemente sea incorrecta.
- Un adaptador representa una costura hipotética; dos adaptadores son una costura real. No introduzcas una costura a menos que realmente haya algo que varíe a ambos lados de ella.
Diseñando para la testabilidad
Una buena interfaz hace que las pruebas sean naturales:
-
Recibe dependencias, no las crees tú mismo.
# Probable def fetch_alternates(mpn: str, client: PartSearchClient) -> list[Part]: ... # Difícil de probar def fetch_alternates(mpn: str) -> list[Part]: client = DistributorClient(api_key=os.environ["DIST_API_KEY"]) -
Devuelve resultados, no generes efectos secundarios.
# Probable def landed_cost(bom: Bom, freight: Freight) -> Money: ... # Difícil de probar def apply_landed_cost(bom: Bom) -> None: bom.total += freight_charge -
Superficie pequeña. Cuantos menos métodos, menos pruebas necesitas; cuantos menos parámetros, más simple es preparar las pruebas.
Relaciones
- Un módulo tiene exactamente una interfaz (la superficie que presenta a los llamadores y las pruebas).
- La profundidad es una propiedad del módulo, medida por su interfaz.
- La costura es el lugar donde está la interfaz del módulo.
- Un adaptador está en una costura y satisface la interfaz.
- La profundidad genera apalancamiento para los llamadores y localidad para los mantenedores.
Marcos que no se adoptan
- Definir profundidad como la relación entre líneas de implementación y líneas de interfaz (Ousterhout): esto premia implementaciones infladas. En su lugar, usamos "profundidad = apalancamiento".
- Equiparar "interfaz" con
Protocol/clase abstracta de Python, o con los métodos públicos de una clase: demasiado estrecho: aquí la interfaz incluye todo lo que el llamador debe saber. - "Límite" (boundary): se confunde con el contexto delimitado de DDD. Usa costura o interfaz.
Lecturas adicionales
- Cómo profundizar un conjunto de módulos bajo dependencias existentes, consulta DEEPENING.md: clasificación de dependencias, disciplina de costuras, y estrategia de pruebas "reemplazar, no añadir".
- Explorar diferentes diseños de interfaz, consulta DESIGN-IT-TWICE.md: lanza múltiples subagentes en paralelo, diseñan interfaces de formas radicalmente distintas, y luego se comparan en términos de profundidad, localidad y ubicación de costuras.