← Índice de la guía
Guía
Patrones de diseño de software para la obra civil
Parte
I · Las bases
Capítulo
1
Estado
Borrador
Patrones
Lenguaje ubicuo (Ubiquitous Language) · Diseño guiado por el modelo (Model-Driven Design)

El glosario del contrato

Cómo lograr que todos, y el código también, usen cada palabra con un solo sentido.

1Primero, el avance de la obra

El edificio tiene seis plantas, con locales comerciales abajo. A los ocho meses, el propietario pregunta cuánto se avanzó. El supervisor y el contratista contestan con números distintos.

«avance» dice el supervisor dice el contratista 100 % 0 40 % Avance físico lo ejecutado 50 % Avance financiero lo pagado
La palabra «avance» da dos números sobre la misma escala. El supervisor mide lo ejecutado, 40 %, y el contratista cuenta lo pagado con el anticipo, 50 %.

Ninguno se equivocó. El supervisor mide con el cómputo métrico, ítem por ítem, y valora lo ejecutado con los precios unitarios del contrato. El contratista cuenta lo pagado sobre el monto del contrato, con un anticipo que se descuenta de las planillas más adelante. Los dos dijeron «avance».

El propietario oyó «50», entendió que la mitad del edificio estaba hecha y pidió a la entidad que financia la obra el desembolso del crédito que se libera a la mitad. El perito de la entidad midió 40 % y no lo autorizó.

La arquitecta redacta una cláusula de definiciones, y el propietario y el contratista la firman como adenda al contrato. Avance físico es lo ejecutado y aprobado por el supervisor. Avance financiero es lo pagado, anticipo incluido, sobre el monto del contrato. Las planillas de avance, los informes y las actas llevan siempre los dos términos, y «avance» sin apellido ya no se escribe.

Hay un segundo problema, más lento. En el décimo mes, el propietario pide correr un tabique metro y medio. Marta, la residente de obra, lo acuerda de palabra con él, sin el supervisor, y nadie corrige los planos. El poliducto eléctrico empotrado se corre con el tabique. Dos años después, el administrador manda picar un muro para pasar un cable, por donde el plano indica que no hay tubería, y la amoladora corta el poliducto.

La obra bien dirigida tiene una regla. Un cambio no existe hasta que es una orden de cambio escrita y firmada por el supervisor, que dice qué se modifica, cuánto cuesta y qué planos toca. Cada plano afectado se emite en revisión nueva, el libro de órdenes deja constancia y, al terminar, la planoteca guarda los planos conforme a obra, que muestran lo construido y no lo proyectado.

Funciona porque una palabra o un plano solo cambian por un trámite, que los deja al día en todos los documentos a la vez.

2El mismo problema, en la app del banco

La app de banca móvil muestra las cuentas y permite transferir por QR. Antes de seguir, tres palabras. Un programa es una serie de instrucciones que una computadora ejecuta; el código es el texto en que están escritas, y un servidor es una computadora que atiende los pedidos de otras, como la que responde a la app del celular.

Hay palabras con dos sentidos, uno en la obra y otro en el programa (servicio, transacción, versión, prueba de carga). El glosario del capítulo 28 las separa.

Rosa, clienta del banco, tiene 1.000 Bs en su caja de ahorro, y 300 están retenidos por una compra con tarjeta de débito autorizada y todavía no liquidada. La app y el extracto le muestran un «saldo» distinto, y el reclamo llega a la gerente.

App: «Saldo» lo muestra disponible 700 Bs retenido 300 Bs contable: 1.000 Bs lo muestra Extracto: «Saldo»
La app y el extracto llaman «saldo» a dos números distintos. De los 1.000 Bs de la cuenta, 300 están retenidos, así que la app muestra 700 y el extracto 1.000.

—¿Cuál es el saldo de Rosa? —pregunta la gerente.

—Depende de qué se cuente —responde el programador—. La app muestra el disponible y el extracto, el contable. En el código los dos se llaman «saldo», porque en las reuniones todos decían «saldo».

Es el avance de la obra, y hay algo peor. La regla de transferir dice «el saldo debe alcanzar» y se escribió con el contable. Rosa podría transferir 900 Bs con 700 disponibles y, al liquidarse la compra, la cuenta quedaría sobregirada sin que nadie lo hubiera decidido.

3Las dos piezas

1El lenguaje ubicuoUbiquitous Language

Es la cláusula de definiciones. Ubicuo quiere decir presente en todas partes, y aquí son las mismas palabras en las reuniones, los documentos, las pantallas y los nombres del código.

TérminoSignificado
Saldo contableLa suma de los movimientos registrados. Es el del extracto.
Saldo retenidoLa parte del contable apartada y no gastable, como una compra con tarjeta aún no liquidada.
Saldo disponibleEl contable menos el retenido. Lo muestra la app y lo controla toda transferencia.

«Saldo» sin apellido no figura, igual que «avance» en el contrato. Cada glosario rige en un área del negocio, y «cuenta» o «cliente» pueden significar otra cosa en otra, como se ve en el capítulo 12.

Por lo tanto

las palabras se fijan una vez, por escrito y de común acuerdo, y todos las usan igual en la reunión, en el papel y en el código.

2El diseño guiado por el modeloModel-Driven Design

Es mantener los planos al día con lo construido, con la orden de cambio como trámite. Tiene tres partes.

Si un día se autoriza el sobregiro en las cajas de ahorro, el disponible pasa a ser el contable menos el retenido más el sobregiro, y la definición y el cálculo cambian en el mismo cambio. Es un modelo vivo. Uno que se hizo al empezar y quedó archivado es el plano de proyecto que nadie actualizó. Sirve para cotizar y no para abrir un muro dos años después.

Por lo tanto

el código se escribe con las palabras del modelo, y cuando una regla cambia se cambian juntos el glosario y el código.

4Qué se gana y qué cuesta

Lo que se gana

  • Menos malentendidos entre la gerente, el programador y Rosa.
  • Reglas que se revisan con quien conoce el negocio, sin traducir.
  • Cambios de regla fáciles de ubicar, porque la palabra es la misma en todas partes.

Lo que cuesta

  • Ponerse de acuerdo lleva reuniones, y discutir una palabra suele ser discutir una regla.
  • Renombrar cuando el lenguaje cambia, y algunos nombres ya los leen otros sistemas.
  • Un glosario que se quedó atrás es peor que ninguno, porque se le cree.

Y la tecnología. El contrato dice «avance físico» lo mismo si la estructura es de hormigón que de acero. Con el glosario pasa igual, y el material del programa, que son los lenguajes y las herramientas de los capítulos 26 y 27, puede cambiar sin tocarlo.

Cuándo no conviene. Una ampliación de un cuarto con un maestro de confianza no necesita cláusula de definiciones. Un glosario formal tampoco paga su costo en un programa chico, de una persona y casi sin reglas.

Con qué se combina. Con las capas, que se ven en el capítulo 2; con las entidades y los objetos de valor, en el capítulo 4, y con los contextos, que dicen dónde rige cada glosario y se ven en el capítulo 12.

5Para llevarse

En la obraEn la app del bancoPatrón
Cláusula de definiciones; «avance» siempre con apellidoGlosario del negocio; «saldo» siempre con apellidoUbiquitous Language
Orden de cambio firmadaCambio de regla con glosario y código en el mismo cambioModel-Driven Design
Planos conforme a obraCódigo que dice lo mismo que el modeloModel-Driven Design

¿No basta con que el programador entienda el negocio?

La residente que conoce cada detalle no reemplaza a los planos, porque un día se va y se lleva lo que sabía. Lo que está en el glosario y en el código lo hereda quien llegue después.

Dónde cojea la analogía

Los planos conforme a obra se dibujan después, y describen un edificio que ya está en pie y se sostiene solo. En el programa no hay obra aparte del plano, porque el código es a la vez lo que se describe y lo que se ejecuta. Si el glosario y el código discrepan, manda el código, y el glosario miente sin que se note.

Tampoco se lee igual. Una cláusula la interpreta una persona, que puede preguntar; el código ejecuta lo escrito.

En la práctica, a noviembre de 2026. El desarrollo guiado por el comportamiento (Behavior-Driven Development) lleva el glosario a las pruebas automáticas, que se ven en el capítulo 20, con reglas escritas como ejemplos en el idioma del negocio que la computadora comprueba. Lo permiten Cucumber (Java, Ruby, JavaScript), Reqnroll (.NET) y behave (Python). El mapa de tecnologías está en el capítulo 28.

Capítulo 2 · CapasCada elemento se apoya solo en lo que tiene debajo.