Diagramme d'Architecture
Un diagramme est compris lorsque ce qu'il montre s'arrime à ce que le lecteur sait déjà. Un développeur senior le lit pour le flux de plus haut niveau et pour les jointures. Un bloc est une boîte noire : son motif de conception, sa responsabilité, son propriétaire, et son intérieur caché. Ce qu'un bloc offre à un autre à travers une jointure est son interface : des opérations avec leurs types de paramètres et de retour, les erreurs, les types de données qui la traversent avec leurs champs, et un exemple de ce qui traverse exactement et à quoi cela ressemble. Le transport (REST, OPC UA, un démarrage de processus) est un attribut d'une interface et ne la remplace jamais.
Lisez EXAMPLE.md avant de dessiner : un changement, complet, sous les deux formes.
Étapes
1. Les mots du lecteur
Un nouveau terme ne s'arrime à rien. Avant toute chose, recueillez les mots que le lecteur possède déjà : à partir de ses messages dans cette conversation, des documents qu'il a écrits (instructions du projet, pages d'architecture, glossaires, tables de nomenclature), et de tout modèle auquel le diagramme est comparé. Rédigez la liste de mots : la chose, le mot du lecteur pour celle-ci, le mot de chaque autre partie qui lira le diagramme, le nom dans le code, et le mot utilisé par le diagramme.
- Étiquetez chaque bloc et interface avec le mot du lecteur ; le nom du code se tient à côté.
- Là où deux mots s'opposent, ou qu'un mot est utilisé pour la mauvaise chose, choisissez-en un, dites pourquoi dans la liste de mots, et nommez l'autre à côté une fois.
- N'inventez rien. Une interface sans nom dans le code est appelée par ses deux extrémités,
Frontend -> Backend. - Partez de l'image que le lecteur possède déjà, son propre diagramme avec ses niveaux et ses noms, et placez ce qui est nouveau à l'intérieur.
Terminé lorsque chaque étiquette sur un diagramme provient de la liste de mots, et que chaque terme nouveau pour le lecteur se trouve dans le glossaire à côté du mot connu auquel il appartient.
2. Questions
Rédigez les questions du lecteur, une par ligne. Ce sont elles qui choisissent les vues.
| Question | Vue |
|---|---|
| Quelles sont les parties, de quoi chacune est-elle responsable, qui la possède, qui appelle qui ? | vue des blocs de construction |
| Quelle interface relie deux parties, et qu'est-ce qui la traverse exactement ? | l'interface, ses types de données et un exemple sur chaque jointure |
| Que se passe-t-il, dans quel ordre, dans le scénario qui importe ? | vue d'exécution : une séquence |
| Où chaque partie s'exécute-t-elle ? | host: sur chaque bloc ; une vue de déploiement lorsque les réseaux ou les limites de confiance sont la question |
| Que fait un changement, ou en quoi deux conceptions diffèrent-elles ? | chaque état sous la même forme, puis les différences |
Terminé lorsque chaque vue a sa question et que la question se trouve au-dessus d'elle comme légende.
3. Catalogue
Remplissez quatre listes à partir des sources avant tout dessin.
- Blocs : le mot du lecteur et le nom dans le code, stéréotype, une phrase de responsabilité, propriétaire, hôte.
- Interfaces, une par jointure : fournisseur, consommateurs, chaque opération comme signature
nom(param: Type) -> Type, erreurs, transport. - Types de données : chaque type nommé par une signature, avec ses champs, unités et valeurs par défaut.
- Exemples, un par interface : un message tel qu'il traverse, appel et réponse dans leur format réel : une ligne de commande avec sa sortie, un corps JSON, une ligne de tableau. Prenez-le à partir d'une exécution, d'un enregistrement, d'un fichier de test ou des données. Un exemple assemblé à partir du code le dit dans sa première ligne.
Chaque entrée porte son origine : une référence de code chemin:ligne, ou une balise (ci-dessous). Un état dessiné par quelqu'un d'autre, un fichier de modèle ou une esquisse, est reproduit tel quel et dans ses propres mots ; ce qu'il omet est balisé [non défini], et ce que vous ajoutez va dans un état qui vous est propre.
Terminé lorsque chaque bloc a sa phrase, chaque jointure une interface dont les signatures sont copiées du code ou balisées, chaque type dans une signature ses champs, chaque interface son exemple, et chaque entrée une référence ou une balise.
4. Niveau
Les blocs d'un état sont des pairs : des unités qui sont déployées, possédées ou remplacées indépendamment, de cinq à neuf d'entre eux. Les fichiers, fonctions et étapes à l'intérieur d'un bloc sont son intérieur. Un zoom est un diagramme supplémentaire un niveau plus bas, dessiné pour le seul bloc concerné par la question.
Terminé lorsqu'aucun bloc d'un état ne se trouve à l'intérieur d'un autre, et que chaque zoom nomme la question qui le justifie.
5. Forme
- Forme de discussion, jusqu'à 78 colonnes : la vue des blocs de construction avec le nom de l'interface et sa signature principale sur chaque arête, puis le catalogue sous forme de tableaux et les exemples sous forme de blocs de code. Pour un état ou un petit changement.
- Forme Canvas, une page HTML statique de diagrammes textuels aussi larges que nécessaire : à côté de chaque arête, son interface en entier, l'exemple, et les types de données avec leurs champs. Pour plusieurs états, ou lorsque plus de trois jointures sont montrées en entier. La page est construite par un script générateur qui se trouve à côté ; la réponse dans le chat nomme le fichier, dit en quelques phrases ce que la comparaison montre et liste les décisions ouvertes.
- Forme C4, le même modèle dessiné avec LikeC4 sur une page avec un onglet par état, des boîtes cliquables et dans lesquelles zoomer. Les diagrammes textuels sont son prototype : fixez les mots, blocs, interfaces et exemples d'abord, puis rendez. Pour un résultat que d'autres personnes ouvriront. Lisez LIKEC4.md.
6. Dessinez
Dessinez avec les trois fichiers de ce dossier, afin que les boîtes soient alignées et qu'aucune ligne ne soit plus large que son canevas. Le docstring de chaque fichier est son manuel, et son exécution imprime une démo.
| Fichier | Donne |
|---|---|
grid.py | Grille (boîtes avec compartiments, lignes, flèches), séquence (une vue d'exécution), tableau |
canvas.py | coup_doeil (chaque état sur une ligne), aperçu (états côte à côte, une ligne par niveau), panneau (un état : blocs, interfaces avec exemples, types de données) |
page.py | page_html : la page autour des diagrammes, avec les couleurs et les liens entre les identifiants |
likec4/ | pour la forme C4 : template.c4, build.sh, la page à onglets index.html avec tabs.js, et clicktest.py |
Une page va de l'image en dix secondes au détail : d'un coup d'œil, la liste de mots, le guide de lecture, l'aperçu, un panneau par état, les différences par jointure sous forme de tableau, les décisions ouvertes, le glossaire, les sources.
7. Vérification
- Chaque boîte est un bloc du catalogue, chaque arête une interface, chaque boîte de type un type de données ; une entrée omise d'un diagramme est omise intentionnellement.
- Chaque référence de code se résout : le fichier existe et la ligne montre le nom.
- Le même bloc se trouve à la même place dans chaque état. Un bloc manquant dans un état est une boîte en pointillés à cet endroit.
- Captures d'écran de la page entière, lues tuile par tuile : les bordures se rejoignent, rien n'est coupé, les couleurs portent leur signification.
- Les sources nomment ce qui a été lu, à quel commit, quels exemples sont réels, et ce qui n'a pas été lu.
États
Un état est le code tel qu'il est, une cible dessinée par quelqu'un, ou une proposition. Comparez les états par position : le même bloc dans la même colonne de coup_doeil et la même ligne de aperçu, de sorte que les lacunes de deux états montrent où ils se complètent.
Une jointure a un identifiant composé d'une lettre pour son état et d'un numéro, (I4). Une interface ou un type de données défini à une jointure est référencé par cet identifiant partout ailleurs ; ses champs sont écrits une seule fois.
Les différences sont un tableau avec une ligne par jointure et une colonne par état. Les décisions ouvertes sont un tableau : la question, les options, qui décide.
Balises et stéréotypes
| Balise | Signification |
|---|---|
[code] | existe dans le code ; la référence se tient à côté |
une balise source, p. ex. [c4] | déclaré par un modèle source ; nommez la balise dans le guide de lecture |
[proposé] | proposé ici, n'existe nulle part encore |
[nouveau] [modifié] [déplacé] | ce qu'un changement fait, lorsqu'il n'y a que l'actuel et le futur |
[non défini] | l'état le laisse ouvert |
[?1] | une décision ouverte, listée avec son numéro |
Les stéréotypes nomment le motif de conception qu'un bloc joue : <<ui>>, <<client>>, <<passerelle>>, <<façade>>, <<service>>, <<port>>, <<adaptateur>>, <<référentiel>>, <<externe>>. Utilisez-en un là où le code joue ce rôle ; un bloc sans stéréotype vaut mieux qu'un bloc avec un mauvais. Un port est une interface que le consommateur possède et que le fournisseur implémente : <<port>> se tient sur l'interface, <<adaptateur>> sur le bloc qui l'implémente. Les propres types d'un modèle source sont cités tels qu'il les écrit.
Dispositifs d'explication
Chacun d'eux mérite sa place en répondant à quelque chose que le lecteur aurait autrement dû demander. Utilisez-les avec parcimonie.
- Guide de lecture : un petit diagramme qui montre comment lire un panneau, et les balises.
- Références de code : sur chaque interface et type de données, afin que le lecteur puisse les consulter.
- Textes courts : un paragraphe au-dessus d'un état qui dit la chose à y voir ; une note à l'intérieur d'une boîte d'interface là où le lecteur demanderait pourquoi.
- Glossaire : les termes que la liste de mots ne couvre pas, un par ligne.
- Couleur : uniquement pour les balises, les identifiants, et un ou deux noms
cléqui restent les mêmes dans tous les états. La couleur marque ce que les états partagent et où ils diffèrent ; rien d'autre n'est coloré.
La prose est dans la langue de la conversation. Les noms provenant du code et des modèles sources sont reproduits textuellement.