🌍 Langues:
🇬🇧 English | 🇫🇷 Français (ce fichier)
FirstClassErrors vous fournit des outils. Ce guide vous aide à les utiliser de manière cohérente et porteuse de sens.
L’objectif n’est pas seulement de lever des exceptions, mais d’exprimer les erreurs de façon claire, précise et utile pour des humains.
La prose que vous rédigez ci-dessous (titre, description, règle, causes, …) peut être écrite en dur ou lue depuis des ressources localisées, afin de générer le catalogue en plusieurs langues — voir Internationalisation.
Chaque erreur documentée doit représenter :
une situation précise dans laquelle le système ne peut pas continuer comme prévu
Évitez les erreurs vagues ou génériques comme :
- « Opération invalide »
- « Erreur de traitement »
- « Problème inattendu »
Préférez des situations précises et contextualisées :
- « Incohérence de devise des montants »
- « Température sous le zéro absolu »
- « Date de transaction hors période du relevé »
Une erreur doit décrire ce qui s’est mal passé en termes métier, pas la réaction du système.
Le code d’erreur est l’identifiant stable, lisible par machine.
Bonnes pratiques :
- Utiliser un périmètre métier clair
AMOUNT_CURRENCY_MISMATCH - Le garder stable dans le temps
- Éviter les détails techniques (pas de noms de classes, pas de noms de méthodes)
- Un code = une situation d’erreur documentée
Considérez le code d’erreur comme un contrat d’API.
Le titre est un résumé humain court.
Il doit :
- être concis
- décrire la situation, pas la conséquence
- éviter le vocabulaire technique
Bon :
- « Incohérence de devise des montants »
- « Température sous le zéro absolu »
À éviter :
- « InvalidAmountOperationError »
- « L’opération a échoué »
La description explique la signification de l’erreur.
Un bon schéma est :
« Cette erreur survient en essayant de… »
ou
« Cette erreur survient lorsque… »
Vous pouvez choisir la formulation qui convient le mieux, mais restez cohérent au sein du projet. La cohérence dans la formulation améliore la lisibilité et rend la documentation plus homogène.
La description doit :
- décrire la situation en langage simple
- être compréhensible par quelqu’un qui ne connaît pas le code
- expliquer ce qui s’est passé, pas comment le système a réagi
La règle exprime l’invariant ou la contrainte métier.
Elle doit :
- être formulée comme une vérité générale
- décrire ce qui doit toujours être respecté
Exemples :
- « Toutes les opérations monétaires doivent impliquer des montants exprimés dans la même devise. »
- « La température ne peut pas descendre sous le zéro absolu. »
S’il n’y a pas de règle explicite, il est acceptable d’omettre cette section.
Une cause décrit une raison plausible de l’erreur.
Elle doit :
- décrire un état ou une condition, pas une action
- éviter toute accusation
- être suffisamment précise pour guider l’investigation
Bon :
- « Des montants ont été utilisés dans une opération monétaire sans avoir été convertis dans la même devise. »
À éviter :
- « Le développeur a oublié de convertir la devise. »
- « Corriger les données. »
Une piste d’analyse suggère où regarder en premier.
Elle doit :
- commencer par un verbe neutre comme Vérifier, Contrôler, Examiner
- guider l’investigation, pas définir des procédures
- éviter les détails de processus de support
Bon :
- « Vérifier si tous les montants impliqués ont été convertis dans une devise commune avant d’être utilisés ensemble. »
À éviter :
- « Ouvrir un ticket. »
- « Contacter l’équipe X. »
Les exemples illustrent l’apparence de l’erreur en pratique.
Ils doivent :
- utiliser des valeurs réalistes
- être simples et clairs
- mettre en évidence la violation de la règle, pas des cas extrêmes
Les exemples ne sont pas des tests — ils ont un rôle pédagogique.
La documentation des erreurs doit se concentrer sur :
- le sens métier
- les règles violées
- les causes plausibles
Évitez d’y faire apparaître :
- des stack traces
- des détails du framework
- des noms de classes internes
Les éléments ci-dessus décrivent la documentation d’une erreur. En complément, chaque factory définit les trois messages que l’erreur porte à l’exécution, via le builder étagé Type.Create(code, diagnosticMessage, …).WithPublicMessage(shortMessage, detailedMessage) :
| Message | Obligatoire | Public | Exposition |
|---|---|---|---|
ShortMessage |
Oui | Utilisateurs finaux / API | Résumé public sûr (par ex. un title RFC 9457). |
DetailedMessage |
Non | Utilisateurs finaux / API | Détail public maîtrisé, exposé uniquement si l’application le décide (par ex. un detail RFC 9457) ; jamais sensible ni interne. |
DiagnosticMessage |
Oui | Logs, support, développeurs | Détail de diagnostic interne (identifiants, valeurs fautives, état interne) ; jamais exposé aux clients externes par défaut. |
Gardez le message de diagnostic riche et technique ; gardez les messages publics sûrs et exempts de détail interne. error.ToException() utilise le message de diagnostic comme Message de l’exception. Lorsque l’erreur est exposée en HTTP, son Code est le type RFC 9457 naturel : exposez-le comme un URI stable tel que urn:problem:{service}:{code}, où {code} est le code d’erreur en minuscules et en kebab-case — par exemple urn:problem:temperature-simulator:temperature-below-absolute-zero ou urn:problem:banking-api:money-transfer-amount-not-positive — afin que les clients puissent aiguiller sur le type de problème (type et status restent l’affaire de l’application).
Quand vous écrivez une erreur :
| Élément | Rôle |
|---|---|
| Code d’erreur | Identifiant stable |
| Message court | Résumé public sûr |
| Message détaillé | Détail public maîtrisé (optionnel) |
| Message de diagnostic | Interne, pour logs et support |
| Titre | Résumé humain court |
| Description | Signification de l’erreur |
| Règle | Invariant violé |
| Cause | Pourquoi cela a pu arriver |
| Piste d'analyse | Où commencer l’investigation |
| Exemples | À quoi cela ressemble |
Des erreurs bien écrites ne sont pas simplement levées. Elles deviennent une partie de la compréhension partagée du fonctionnement — et des échecs — du système.