Ubiquitous Language

Un seul vocabulaire pour parler, coder, documenter — éliminer les traductions implicites entre métier et tech qui sont la principale source de bugs sémantiques.

Problème

Dans une réunion de spec EDI, le métier dit « quand on facture, on génère la facture ». Le développeur entend « créer un Invoice en base ». Le testeur entend « émettre un INVOIC EDIFACT ». L'architecte d'intégration entend « publier l'événement InvoiceIssued ». Quatre traductions silencieuses, quatre mises en œuvre qui ne couvrent pas le même périmètre. En production, on découvre que « facturer » signifie en réalité : créer en base, valider, signer Factur-X, envoyer via AS4, archiver 10 ans, et notifier le client. Six choses, un seul mot. Le mot ne porte pas la sémantique.

Forces

• Le métier utilise des mots polysémiques. « Facture » = document, processus, événement, acte juridique, ligne comptable — selon le contexte.
• Les développeurs traduisent dans leur tête. Si la traduction est implicite, deux développeurs traduisent différemment.
• Le code et la documentation divergent. La spec dit « facture », le code dit Bill, l'event dit InvoiceCreated, le partenaire dit INVOIC. Quatre vocabulaires.
• La séniorité métier disparaît. Le seul expert qui savait ce que « clôturer la facture » voulait dire change de poste. Sans glossaire écrit, la connaissance s'évapore.

Solution

Construire avec le métier un glossaire ubiquitaire par bounded context. Chaque terme reçoit : une définition précise, un exemple, un anti-exemple (« ne pas confondre avec… »), le synonyme externe (EDIFACT, X12, partenaire) et la correspondance code. Le glossaire est versionné en git, dans le repo du contexte, à côté du code. Le code source utilise les termes du glossaire dans les noms de classes, méthodes, événements, tables DB. Les noms de réunion utilisent les mêmes termes. Les PRs sont relues sur ce critère.

Contexte Facturation — glossaire ubiquitaire :

  Invoice              ≠ Bill ≠ Receipt ≠ Statement
  IssuedAt             — datetime émission par le fournisseur
  ReceivedAt           — datetime réception par notre hub
  CreditTerm           — durée en jours avant échéance
  Debtor               — entité qui doit payer
  Creditor             — entité qui doit recevoir le paiement
  PaymentTerms         — modalités (90j net, escompte 2% à 10j…)
  InvoiceLine          — ligne de facture (jamais "ligne tout court")
  TotalAmountExclVAT   — montant hors taxes
  TotalAmountInclVAT   — montant toutes taxes comprises

  Verbes :
  - "facturer"  → IssueInvoice (commande)
  - "envoyer"   → SendInvoice  (action technique transport)
  - "déposer"   → DeliverInvoice (réception côté débiteur)
  - "recouvrer" → CollectPayment (encaissement)

Implémentation EDI

Cas concret : une équipe EDI rédige son glossaire du contexte « Facturation B2B » : « Émettre une facture » (issue) = créer l'enregistrement dans le système & assigner un numéro de facture séquentiel ; « envoyer une facture » (send) = transmission au partenaire via AS2/AS4 ; « déposer une facture » (deliver) = transmission CTC à la plateforme fiscale réglementaire (Chorus Pro, PEPPOL) ; « encaisser » (collect) = recevoir le règlement. Les événements Kafka deviennent InvoiceIssued, InvoiceSent, InvoiceDelivered, PaymentCollected. Les interfaces partenaires (INVOIC EDIFACT, 810 X12) sont mappées en annexe du glossaire. Pareil pour le contexte « Hospitalier » : « Patient » ≠ « Visiteur » ≠ « Bénéficiaire » ≠ « Personne » — chacun avec son scope précis.

Anti-patterns

• Glossaire imposé top-down par la tech. Sans le métier, les termes ne sont pas adoptés et le code utilise une langue isolée.
• Glossaire unifié sur toute l'organisation. « Une seule définition de Client pour tout le groupe » : vouée à l'échec. Un glossaire par bounded context, des traducteurs aux frontières.
• Glossaire qui dort dans Confluence. S'il n'est pas dans le repo du code et relu en PR, il dérive du code en six mois. Le mettre à côté du code (markdown).
• Mots ambigus tolérés « parce que tout le monde sait ». « Tout le monde » est l'expert qui part en retraite. Forcer la définition écrite.

Patterns liés

• Bounded Context — chaque contexte a son glossaire propre.
• Anti-Corruption Layer — l'ACL traduit du glossaire externe vers l'interne.
• Domain Event — les noms d'événements suivent l'ubiquitous language.
• Aggregate — les noms d'aggregates et leurs méthodes suivent l'ubiquitous language.

Sources

• Evans E. — Domain-Driven Design, Addison-Wesley 2003. Chap. 2 « Communication and the Use of Language ».
• Fowler M. — UbiquitousLanguage (martinfowler.com, 2006). La synthèse pédagogique. martinfowler.com — UbiquitousLanguage
• Vernon V. — Implementing Domain-Driven Design, Addison-Wesley 2013. Chap. 1 et 2 détaillent la construction du glossaire ubiquitaire.
• Brandolini A. — Event Storming. La méthode atelier pour faire émerger l'ubiquitous language avec le métier. eventstorming.com
• ddd-crew — Bounded Context Canvas. Outil pour documenter le bounded context et son ubiquitous language. github.com/ddd-crew/bounded-context-canvas