17. Documentación del diseño detallado: módulos, clases, contratos y dependencias
17.1 Introducción
La documentación del diseño detallado describe cómo se organiza internamente una parte del sistema para cumplir una funcionalidad o responsabilidad técnica. Se ubica por debajo de la documentación de arquitectura: mientras la arquitectura muestra la estructura principal, el diseño detallado explica módulos, clases, contratos, dependencias y reglas internas relevantes.
No todo detalle de implementación debe documentarse fuera del código. El objetivo no es repetir cada archivo, método o línea. El objetivo es explicar decisiones internas que una persona necesita comprender para modificar, extender, probar o mantener el sistema con menor riesgo.
Este tipo de documentación es especialmente útil cuando una parte del software tiene lógica compleja, muchas dependencias, reglas delicadas, contratos internos importantes o decisiones que no se entienden fácilmente leyendo el código.
17.2 Qué es diseño detallado
El diseño detallado describe cómo se resuelve una parte del sistema a nivel interno. Puede incluir estructura de módulos, responsabilidades de clases o servicios, contratos entre componentes, dependencias, flujos técnicos, validaciones, algoritmos, patrones utilizados y restricciones de implementación.
Mientras la documentación funcional dice qué debe hacer el sistema, el diseño detallado explica cómo se organiza internamente para hacerlo. Por ejemplo, la funcionalidad "reservar turno" puede involucrar un servicio de reservas, un repositorio, una política de disponibilidad, una validación de concurrencia y un publicador de eventos.
17.3 Elementos del diseño detallado
La imagen muestra elementos típicos de la documentación del diseño detallado: módulos, clases importantes, servicios, contratos, dependencias, responsabilidades, flujos internos y pruebas relacionadas. Estos elementos ayudan a comprender cómo se implementa una solución dentro del sistema.
17.4 Módulos
Un módulo agrupa código relacionado con una responsabilidad. Puede representar una funcionalidad, una capa, un paquete, un componente interno o un área del dominio. Documentar módulos permite entender cómo se divide el sistema y dónde debería ubicarse un cambio.
La documentación de un módulo puede incluir su propósito, responsabilidades, límites, dependencias, datos que maneja, servicios que expone y reglas que debe respetar. También conviene indicar qué no debe hacer el módulo para evitar mezcla de responsabilidades.
Por ejemplo, en un sistema de turnos, un módulo de agenda puede administrar disponibilidad de profesionales, pero no debería encargarse de enviar notificaciones si esa responsabilidad pertenece a otro módulo.
17.5 Clases y servicios importantes
No todas las clases necesitan documentación externa. Las clases simples deberían entenderse por sus nombres, código y pruebas. Pero algunas clases o servicios son centrales para el comportamiento del sistema y conviene documentarlos.
Puede ser útil documentar clases que implementan reglas complejas, coordinan varios componentes, encapsulan algoritmos, representan conceptos críticos del dominio o exponen contratos usados por otras partes.
La documentación debe centrarse en responsabilidad, invariantes, colaboraciones y decisiones. No debería repetir una lista automática de métodos si esa información ya está clara en el código o se genera con herramientas.
17.6 Responsabilidades
Las responsabilidades indican qué debe hacer cada módulo, clase o servicio. Documentarlas ayuda a evitar duplicación y acoplamiento innecesario. Cuando una responsabilidad no está clara, el código tiende a crecer en lugares incorrectos.
Una buena descripción de responsabilidad usa verbos concretos: valida disponibilidad, registra reservas, calcula importes, publica eventos, consulta profesionales, transforma datos o aplica permisos.
También conviene documentar límites. Por ejemplo: "El servicio de reservas registra y cancela turnos, pero no envía notificaciones directamente; publica eventos para que otro componente las procese".
17.7 Contratos internos
Un contrato interno define cómo una parte del sistema espera comunicarse con otra. Puede incluir entradas, salidas, errores, excepciones, eventos, formatos, precondiciones y efectos esperados.
Documentar contratos internos es importante cuando varias partes dependen de ellos. Por ejemplo, un servicio puede prometer que al cancelar un turno publicará un evento con identificador del turno, motivo y usuario responsable. Otros componentes pueden depender de ese evento.
Si el contrato cambia sin documentarse, pueden romperse pruebas, integraciones internas o procesos de mantenimiento.
17.8 Dependencias
Las dependencias muestran qué módulos, servicios, librerías o recursos necesita una parte del sistema. Documentarlas ayuda a entender impacto y riesgos. También permite detectar dependencias circulares o acoplamientos innecesarios.
No todas las dependencias deben listarse manualmente. Muchas pueden verse desde el código o herramientas. La documentación debe enfocarse en dependencias relevantes: sistemas externos, librerías críticas, módulos compartidos, servicios con alta disponibilidad requerida o componentes difíciles de reemplazar.
17.9 Flujos internos
Un flujo interno describe cómo colaboran módulos o clases para completar una operación. A diferencia de un flujo funcional, que mira la experiencia del usuario o actor, el flujo interno mira la coordinación técnica.
Por ejemplo, para reservar un turno: el controlador recibe la solicitud, el servicio valida disponibilidad, el repositorio bloquea o consulta el horario, se registra la reserva, se confirma la transacción y se publica un evento de notificación.
Estos flujos pueden documentarse con texto, listas o diagramas de secuencia cuando el orden de mensajes importa.
17.10 Reglas internas e invariantes
Algunas reglas no son visibles directamente para el usuario, pero son esenciales para mantener consistencia interna. Se llaman invariantes cuando deben cumplirse siempre dentro del modelo o módulo.
Por ejemplo, un turno reservado debe tener paciente asociado; un turno atendido no puede volver a disponible; una agenda no debe tener franjas superpuestas para el mismo profesional. Estas reglas pueden estar implementadas en clases, servicios o base de datos.
Documentar invariantes ayuda a quienes modifican el sistema a no romper condiciones fundamentales.
17.11 Patrones y decisiones de diseño
Si una parte del sistema usa un patrón de diseño o una convención técnica importante, conviene documentarlo. Por ejemplo, repositorios para acceso a datos, servicios de aplicación para coordinar casos de uso, adaptadores para integraciones externas o eventos de dominio para desacoplar procesos.
No se trata de explicar teoría general del patrón, sino de indicar cómo se aplica en el proyecto y qué problema resuelve. También conviene señalar restricciones: dónde debe usarse, dónde no y qué errores evitar.
17.12 Relación con pruebas
El diseño detallado debe relacionarse con pruebas. Si un módulo tiene reglas importantes, deberían existir pruebas que las verifiquen. Si un contrato interno es crítico, deberían existir pruebas de integración o contrato.
La documentación puede indicar qué pruebas cubren un módulo, qué escenarios son obligatorios y qué datos se usan para validar casos complejos. Esto ayuda a mantener confianza cuando se realizan cambios.
17.13 Tabla de documentación de un módulo
| Elemento | Qué documentar | Ejemplo |
|---|---|---|
| Propósito | Para qué existe el módulo. | Administrar reservas y cancelaciones de turnos. |
| Responsabilidades | Qué operaciones y reglas concentra. | Validar disponibilidad, registrar reserva, cancelar turno. |
| Contratos | Entradas, salidas, errores y eventos. | Publica evento TurnoReservado. |
| Dependencias | Componentes o recursos necesarios. | Repositorio de turnos, servicio de agenda. |
| Pruebas | Escenarios que verifican el diseño. | Reserva exitosa, horario ocupado, cancelación fuera de plazo. |
17.14 Cuándo documentar diseño detallado
No conviene documentar todo con el mismo nivel de detalle. La documentación de diseño detallado es especialmente útil cuando una parte del sistema es compleja, crítica, compartida por varios equipos, difícil de probar o costosa de modificar.
También conviene documentar cuando el diseño no es evidente desde el código. Por ejemplo, una solución que usa eventos, colas, reintentos, caché o consistencia eventual puede necesitar explicación adicional.
17.15 Documentación cercana al código
La documentación de diseño detallado suele beneficiarse de estar cerca del código. Puede vivir en el repositorio, junto al módulo correspondiente, o en documentos enlazados desde el README del proyecto.
Cuando el diseño cambia junto con el código, mantener la documentación cerca facilita actualización y revisión. Si la documentación queda en una herramienta separada sin relación con los cambios, es más probable que quede obsoleta.
17.16 Errores frecuentes
Al documentar diseño detallado suelen aparecer estos errores:
- Repetir automáticamente el código sin aportar explicación.
- Documentar clases simples y omitir módulos complejos.
- No explicar responsabilidades ni límites de cada módulo.
- Omitir contratos internos usados por varias partes.
- No documentar dependencias críticas.
- Dejar la documentación lejos del código que cambia.
- No relacionar el diseño con pruebas que lo verifican.
17.17 Qué debes recordar de este tema
- La documentación de diseño detallado explica decisiones internas relevantes.
- No debe duplicar todo el código ni reemplazar nombres claros y pruebas.
- Debe enfocarse en módulos, clases importantes, responsabilidades, contratos y dependencias.
- Los flujos internos ayudan a entender colaboración entre partes.
- Las invariantes y reglas internas deben documentarse cuando son críticas.
- El diseño detallado debe relacionarse con pruebas.
- Conviene mantener esta documentación cerca del código cuando cambia junto con él.
17.18 Conclusión
La documentación del diseño detallado ayuda a comprender cómo está construida internamente una parte del sistema. Bien enfocada, reduce riesgos de mantenimiento y evita que el conocimiento quede escondido en código difícil de interpretar.
En el próximo tema estudiaremos la documentación de APIs: endpoints, parámetros, respuestas, errores y ejemplos.