Aller au contenu

Les schémas Mermaid

Mermaid transforme du texte en schéma. On écrit quelques lignes, l'outil dessine. Le schéma vit dans le même dépôt que le code, se modifie comme du code, et se relit dans un commit.

Le problème

Quand un projet dépasse quelques fichiers, on ne peut plus le garder en tête. On perd la vue d'ensemble : qui appelle qui, dans quel ordre, quelles sont les étapes.

Un schéma remet cette vue sous les yeux. Mais un schéma dessiné à la souris est long à faire, et personne ne le met à jour. Un schéma en texte se corrige en dix secondes.

Un schéma répond à une question

L'erreur classique est de vouloir tout montrer. Un bon schéma répond à une seule question. On choisit le type d'après la question.

QuestionType MermaidExemple dans la documentation du jeu
Dans quel ordre ça se passe ? Quels sont les choix ?flowchartA*
Qui appelle qui, et dans quel ordre ?sequenceDiagramTour par tour
Quelles classes existent, que contiennent-elles ?classDiagramLes classes
Dans quels états peut-on être ?stateDiagram-v2Modes en partie
À quoi ressemblent les données ?erDiagramPlus bas sur cette page
Comment c'est rangé ?flowchart avec subgraphLes dossiers

Écrire un schéma dans ce site

Dans un fichier .mdx, on utilise le composant Mermaid :

ReactTSX
<Mermaid chart={`flowchart LR A[Accueil] --> B[Partie]`} />

Pour mettre au point un schéma avant de le coller : mermaid.live affiche le résultat pendant qu'on tape.

flowchart : un déroulé avec des choix

Le plus utilisé. La première ligne donne le sens : LR de gauche à droite, TB de haut en bas.

Code
flowchart LR start([Clic sur une case]) --> q{Mode déplacement actif ?} q -- oui --> move[Déplacer l'unité sélectionnée] q -- non --> select[Sélectionner la case]

Les formes ont un sens, et le respecter aide à la lecture :

ÉcritureFormeUsage
a[texte]RectangleUne action
a{texte}LosangeUne question
a([texte])ArrondiUn début ou une fin
a((texte))CercleUn point, un nœud de graphe
a[(texte)]CylindreDes données stockées

Et les flèches :

ÉcritureRenduUsage
a --> bFlèche pleineEnchaînement
a -- texte --> bFlèche avec étiquetteRéponse à une question
a -.-> bPointillésLien indirect, optionnel
a ==> bTrait épaisLien important

Pour regrouper des boîtes, subgraph nom [Titre] puis end.

sequenceDiagram : qui appelle qui

Chaque colonne est un objet, le temps descend. C'est le meilleur schéma pour repérer une fonction qui touche à trop de choses : plus il y a de colonnes traversées, plus le code est couplé.

Code
sequenceDiagram participant G as Game participant PH as PlayerHandler participant P as Player G->>PH: next_turn() PH->>P: finish_turn() P-->>PH: ressources mises à jour
ÉcritureSens
A->>B: messageA appelle B
B-->>A: réponseB répond à A
Note over A: texteUne remarque
loop texte puis endUne répétition
opt texte puis endUn passage facultatif

classDiagram : les classes et leurs liens

Code
classDiagram class Unit { +name +current_hp +move(tile) +attack(other) } class Settler { +special_action() } Unit <|-- Settler Player *-- Unit : units_owned
ÉcritureSens
A <|-- BB hérite de A
A *-- BA possède B et le crée
A o-- BA garde une référence vers B
A --> BA utilise B
A ..> BA dépend de B, sans le garder

Conseil : ne pas tout mettre. Un schéma avec les seuls liens, puis un schéma détaillé par groupe de classes, se lit mieux qu'un grand schéma complet.

stateDiagram-v2 : des états et des transitions

Idéal pour les menus, et pour tout ce qui est « un mode à la fois ».

Code
stateDiagram-v2 [*] --> Accueil Accueil --> Partie: START Partie --> Pause: ESC Pause --> Partie: ESC Pause --> Accueil: QUIT

[*] marque le début et la fin. Le texte après les deux-points est l'événement qui déclenche le changement.

Ce schéma révèle souvent des oublis : un état dont on ne peut pas sortir, ou une transition qu'on n'avait pas prévue.

erDiagram : la forme des données

Utile pour un fichier de sauvegarde ou une base de données. Voici le fichier save_N.json écrit par Saves_Handler.write_save :

Les symboles entre deux entités indiquent combien : une barre pour « un », une patte d'oie pour « plusieurs », un rond pour « zéro possible ».

La méthode

  1. Écrire la question en une phrase. « Que se passe-t-il quand le joueur finit son tour ? »

  2. Choisir le type dans le tableau du haut.

  3. Dessiner ce qui existe, en lisant le code, sans rien corriger.

  4. Repérer ce qui gêne : flèches qui se croisent, boîte reliée à tout le monde, colonne traversée dix fois.

  5. Dessiner la version souhaitée. L'écart entre les deux schémas est le plan de travail.

L'étape 3 est la plus utile et la plus négligée. Dessiner ce qu'on croit avoir écrit ne sert à rien. Dessiner ce qui est réellement écrit fait apparaître les problèmes.

Les erreurs fréquentes

ErreurEffetCorrection
Trop de boîtesIllisibleUn schéma par question, une quinzaine de boîtes au plus
Texte long dans une boîteBoîtes énormesQuelques mots. Le détail va dans le texte autour
Mélanger les niveauxConfusionNe pas mettre des dossiers et des fonctions dans le même schéma
Aucune légendeLe lecteur devineUne phrase avant le schéma : ce qu'il montre, comment le lire
Schéma jamais mis à jourIl mentLe modifier dans le même commit que le code

Les pièges d'écriture

ProblèmeCauseSolution
Le schéma ne s'affiche pasParenthèses ou deux-points dans une étiquetteMettre l'étiquette entre guillemets doubles
Retour à la ligne dans une boîteÉcrire <br/>
Identifiant refuséMot réservé comme endChoisir un autre identifiant
Accent grave dans le schémaIl ferme le texte du composantNe pas en mettre

À retenir

  • Un schéma, une question.
  • Le type se choisit d'après la question.
  • Dessiner d'abord ce qui existe.
  • Un schéma se met à jour avec le code.

Exercices

  1. Dessiner en flowchart ce que fait la touche B dans le jeu.
  2. Dessiner en sequenceDiagram ce qui se passe quand le joueur fonde une ville avec la touche A. Combien d'objets sont traversés ?
  3. Dessiner en stateDiagram-v2 les états d'une unité : en attente, sélectionnée, en déplacement, morte.
  4. Reprendre un schéma de la documentation du jeu, trouver ce qui a changé dans le code depuis, et le corriger.