From 77d068c0e2299e4d0d1ebed48cca63a032c64860 Mon Sep 17 00:00:00 2001 From: Claude Date: Thu, 16 Jul 2026 06:41:55 +0000 Subject: [PATCH] docs: lead README with the problem before the solution overview Swap the "The problem" and "One model for the whole chain" sections so the README follows a problem-then-solution narrative, and trim the now redundant opening sentence of the model overview. Applied to both the English README and the French translation to keep them in sync. Co-Authored-By: Claude Opus 4.8 Claude-Session: https://claude.ai/code/session_01R79xDspf96YW7bLnWsrgph --- README.md | 38 +++++++++++++++++++------------------- doc/README.fr.md | 38 +++++++++++++++++++------------------- 2 files changed, 38 insertions(+), 38 deletions(-) diff --git a/README.md b/README.md index 6bb6c77f..fdb933a9 100644 --- a/README.md +++ b/README.md @@ -17,25 +17,6 @@ ![FirstClassErrors](./doc/images/first-class-errors.png "FirstClassErrors") -## 🧩 One model for the whole chain - -An application error too often boils down to a bare code or string, with nothing that explains what it actually means. FirstClassErrors turns it into a first-class concept of your domain. You describe each error situation once, with its rules, in one place in the code; the whole library then builds on that model. - -**Model the error** -An error becomes an object that carries its own meaning — a violated business rule, a rejected incoming request, or a failing external service, transient or not. - -**Handle the failure** -You choose how it travels: thrown as an ordinary exception, or returned as an explicit result the caller inspects without a try/catch. - -**Document the error** -Each error can carry its explanation, its rule, and its likely causes right there in the code. FirstClassErrors generates a human-readable catalog from that same code — so it never drifts. - -**Check the model** -Roslyn analyzers enforce these rules at compile time: a duplicated error code or inconsistent documentation becomes a build error, caught before it ever reaches production. - -**Bind external input** -A form or a JSON request must become a valid domain object. Where classic .NET binding restates those rules separately, in a validator or attributes, FirstClassErrors binds that input directly to your value objects, reusing their own construction rules instead of duplicating them. - ## 🚨 The problem A production error is rarely useful as only a type and a string: @@ -54,6 +35,25 @@ Developers and support still need to discover: When that knowledge lives in logs, tickets, comments, and people's memories, it drifts away from the code. +## 🧩 One model for the whole chain + +FirstClassErrors turns an application error into a first-class concept of your domain. You describe each error situation once, with its rules, in one place in the code; the whole library then builds on that model. + +**Model the error** +An error becomes an object that carries its own meaning — a violated business rule, a rejected incoming request, or a failing external service, transient or not. + +**Handle the failure** +You choose how it travels: thrown as an ordinary exception, or returned as an explicit result the caller inspects without a try/catch. + +**Document the error** +Each error can carry its explanation, its rule, and its likely causes right there in the code. FirstClassErrors generates a human-readable catalog from that same code — so it never drifts. + +**Check the model** +Roslyn analyzers enforce these rules at compile time: a duplicated error code or inconsistent documentation becomes a build error, caught before it ever reaches production. + +**Bind external input** +A form or a JSON request must become a valid domain object. Where classic .NET binding restates those rules separately, in a validator or attributes, FirstClassErrors binds that input directly to your value objects, reusing their own construction rules instead of duplicating them. + ## 💡 The FirstClassErrors approach A factory gives the error situation a stable identity, keeps its construction in one place, and attaches structured documentation that will feed a generated, human-readable catalog: diff --git a/doc/README.fr.md b/doc/README.fr.md index 924dbf03..351e5b45 100644 --- a/doc/README.fr.md +++ b/doc/README.fr.md @@ -17,25 +17,6 @@ ![FirstClassErrors](./images/first-class-errors.png "FirstClassErrors") -## 🧩 Un seul modèle pour toute la chaîne - -Une erreur applicative se réduit trop souvent à un code ou une chaîne de caractères, sans rien qui en explique le sens. FirstClassErrors en fait un concept de première classe de votre domaine. Vous décrivez chaque situation d’erreur une seule fois, avec ses règles, à un seul endroit du code ; toute la bibliothèque s’appuie ensuite sur ce modèle. - -**Modéliser l’erreur** -Une erreur devient un objet qui porte son propre sens — qu’il s’agisse d’une règle métier violée, d’un appel entrant rejeté ou d’une panne d’un service externe, passagère ou définitive. - -**Gérer l’échec** -À vous de choisir comment elle voyage : levée comme une exception classique, ou renvoyée comme un résultat explicite que l’appelant inspecte sans try/catch. - -**Documenter l’erreur** -Chaque erreur peut porter, dans le code, son explication, sa règle et ses causes probables. FirstClassErrors en génère un catalogue lisible, extrait de ce même code — il ne dérive donc jamais. - -**Vérifier le modèle** -Des analyseurs Roslyn contrôlent ces règles dès la compilation : un code d’erreur dupliqué ou une documentation incohérente deviennent des erreurs de build, détectées avant la production. - -**Lier les entrées externes** -Un formulaire ou une requête JSON doit devenir un objet métier valide. Là où le binding .NET classique redéclare ces règles séparément, dans un validateur ou des attributs, FirstClassErrors lie ces entrées directement à vos objets valeur, en réutilisant leurs propres règles de construction au lieu de les dupliquer. - ## 🚨 Le problème Une erreur de production est rarement utile lorsqu’elle se résume à un type et une chaîne de caractères : @@ -54,6 +35,25 @@ Les développeurs et le support doivent encore découvrir : Lorsque cette connaissance est répartie entre les logs, les tickets, les commentaires et la mémoire des personnes, elle dérive du code. +## 🧩 Un seul modèle pour toute la chaîne + +FirstClassErrors fait de l’erreur un concept de première classe de votre domaine. Vous décrivez chaque situation d’erreur une seule fois, avec ses règles, à un seul endroit du code ; toute la bibliothèque s’appuie ensuite sur ce modèle. + +**Modéliser l’erreur** +Une erreur devient un objet qui porte son propre sens — qu’il s’agisse d’une règle métier violée, d’un appel entrant rejeté ou d’une panne d’un service externe, passagère ou définitive. + +**Gérer l’échec** +À vous de choisir comment elle voyage : levée comme une exception classique, ou renvoyée comme un résultat explicite que l’appelant inspecte sans try/catch. + +**Documenter l’erreur** +Chaque erreur peut porter, dans le code, son explication, sa règle et ses causes probables. FirstClassErrors en génère un catalogue lisible, extrait de ce même code — il ne dérive donc jamais. + +**Vérifier le modèle** +Des analyseurs Roslyn contrôlent ces règles dès la compilation : un code d’erreur dupliqué ou une documentation incohérente deviennent des erreurs de build, détectées avant la production. + +**Lier les entrées externes** +Un formulaire ou une requête JSON doit devenir un objet métier valide. Là où le binding .NET classique redéclare ces règles séparément, dans un validateur ou des attributs, FirstClassErrors lie ces entrées directement à vos objets valeur, en réutilisant leurs propres règles de construction au lieu de les dupliquer. + ## 💡 L’approche FirstClassErrors Une factory donne une identité stable à la situation d’erreur, centralise sa construction et y attache une documentation structurée qui alimentera un catalogue généré, lisible par des humains :