L’art de concevoir des diagrammes architecturaux

À un moment donné, dans chaque projet logiciel dans lequel nous sommes impliqués, il pourrait y avoir un besoin de créer des diagrammes architecturaux. Que nous suivions un modèle architectural formel (par exemple, Kruchten 4+1, Rozanski & Woods, etc) ou non, il est nécessaire de documenter certaines parties de l’application en créant des diagrammes. En architecture logicielle, de tels diagrammes sont créés en conformité avec les vues qui sont liées à un point de vue spécifique qui pourrait faire partie d’un modèle, mais dans l’article actuel, je préfère m’en tenir au terme diagramme architectural et ne pas être très formel ; tous les autres aspects ne sont pas destinés à être couverts ici.

Sur la base de mon expérience en tant qu’architecte logiciel et formateur technique, il y a beaucoup de divergences entre les projets et à l’intérieur de l’équipe de projet, d’un développeur à l’autre, dans la façon dont les diagrammes architecturaux sont créés. J’ai vu beaucoup de problèmes concernant l’incohérence, la fragmentation et la granularité des informations rendues et l’aspect des diagrammes. Par rapport à un modèle architectural qui doit être formel et normalisé, les diagrammes ne sont pas nécessairement formalisés ou ne suivent pas une norme spécifique.

Néanmoins, les diagrammes doivent être autodescriptifs, cohérents, suffisamment précis et connectés au code. C’est pourquoi il est important que chaque architecte ou ingénieur logiciel s’appuie sur plusieurs lignes directrices lors de la création de diagrammes architecturaux, car ils sont le terrain commun de la communication de l’architecture de l’application au fil du temps (par exemple, la structure, les éléments, les relations, les propriétés, les principes) et à travers différentes parties prenantes ayant des antécédents techniques et des préoccupations diverses.

Pièges courants lors de la conception de diagrammes architecturaux

Avant d’approfondir les problèmes possibles, je voudrais avoir une analogie avec une idiome anglais qui dit « une image vaut mille mots ». Selon cette explication wiki, « cela fait référence à la notion qu’une idée complexe peut être transmise avec une seule image fixe ou qu’une image d’un sujet transmet son sens ou son essence plus efficacement qu’une description ». Le même concept s’applique à un diagramme architectural : s’il soulève plus de questions que de réponses, le diagramme n’est pas bien créé. Ne laissez pas un diagramme architectural nécessiter des milliers de mots ou de clarifications!

Exemple d’un diagramme architectural incorrect. Il souffre de la plupart des problèmes décrits ci-dessous

Détaillons maintenant une liste de pièges qui pourraient entraver le processus de création correcte de diagrammes architecturaux.

Que dénote une boîte ou une forme ?

• L’utilisation de tout type de boîte ou de forme qui n’est pas correctement documentée pourrait entraîner de multiples interprétations. Elle pourrait être associée soit à un morceau de données, soit à un paquet de code, soit à un processus. Juste une simple boîte dans un diagramme pourrait soulever de multiples doutes et il est très important de les éviter en ajoutant explicitement des détails sur la signification de la boîte ou de la forme dans la légende du diagramme.

Que représentent les différents bords d’une forme ?

• Chaque bord d’une forme (par exemple, en pointillés, en tirets, etc.) peut être mal compris dans le cas d’un mauvais diagramme. Une bordure spécifique fait-elle référence à un type de composant spécifique (par exemple, une ligne pointillée fait référence à un conteneur, un microservice, une couche, etc.), ou est-ce simplement la préférence du concepteur pour avoir une apparence riche ? Évitez une telle confusion en fournissant des détails précis dans le diagramme de légende lorsque vous choisissez des bords multiples ou non standard.

Que dénote une ligne ou une flèche ?

• Une ligne ou une flèche peut être interprétée soit comme un flux de données (par exemple, les données circulent du système A au système B), soit comme une relation entre des éléments (par exemple, le composant A dépend du composant B). Dans la plupart des cas, les relations ou les flux de données représentés par les flèches ne convergent pas dans les mêmes directions et il est important de l’écrire explicitement dans la légende du diagramme.

Quel est le type de communication/association indiqué par une ligne ou une flèche?

• Même si la ligne fait référence à un flux de données ou à une relation entre éléments, le type de communication (par exemple en cas de flux de données) ou le type d’association (par exemple en cas de relation) dénoté par cette ligne ou cette flèche doit être détaillé. Par exemple, si la ligne représente un flux de données, la communication peut être synchrone ou asynchrone, mais si la ligne fait référence à une relation, elle peut être représentée par une dépendance, un héritage, une implémentation, etc. Tous ces détails doivent être présents dans la légende du diagramme.

Que signifie cette couleur ?

• Avoir un diagramme policolor ‘perrot’ (par exemple, plusieurs couleurs pour les boîtes, les lignes) sans aucune intention documentée appropriée pourrait soulever de multiples questions (par exemple, pourquoi certaines boîtes sont-elles vertes et d’autres rouges ? Pourquoi certaines lignes sont-elles noires et d’autres bleues ?). Le schéma de couleurs est moins important dans un diagramme, et l’utilisation d’un grand nombre de couleurs n’apporte pas trop de contenu supplémentaire ou d’informations précieuses. Un diagramme peut également être explicite et bien conçu en utilisant simplement des couleurs noires et blanches, à moins qu’il n’y ait une contrainte stricte pour mettre en valeur certaines parties du diagramme en utilisant des couleurs distinctes. Dans tous les cas, il est toujours préférable de s’en tenir à la simplicité en termes de couleurs utilisées, mais si ce n’est pas le cas, n’oubliez pas de détailler le choix.

Les relations manquantes entre les éléments du diagramme ou les entités isolées

• Les relations manquantes entre les éléments ou les entités isolées dans un diagramme pourraient être un indice d’incomplétude. D’un point de vue structurel et comportemental, chaque élément ou entité devrait s’appuyer sur / avoir une relation (représentée par une ligne ou une flèche) avec une autre partie du système représentée par un élément différent.

Acronymes trompeurs/non documentés ou termes trop vagues/génériques

• Lors de l’utilisation d’une étiquette pour un élément dans un diagramme, il est recommandé de ne pas utiliser d’acronyme trompeur ou non documenté qui pourrait entraîner des confusions. Une simple séquence de lettres (par exemple TFH, RBPM) ne signifie rien sans une explication appropriée sur l’élément du diagramme ou, encore mieux, dans la légende du diagramme (par exemple TFH – ticket feed handler, RBPM – rates business process manager).

• Une autre caractéristique de la dénomination des éléments du diagramme concerne des termes extrêmement vagues ou génériques (par exemple logique métier, logique d’intégration) qui n’apportent pas trop d’informations précieuses parce que leurs noms ne sont pas correctement auto-descriptifs. Ce problème pourrait résider au niveau du code également, et la suggestion serait de toujours utiliser des noms auto-explicatifs et suggestifs en suivant sur les principes du code propre.

Emphaser les technologies, les cadres, les langages de programmation ou de script, l’IDE ou la méthodologie de développement sur les diagrammes

• La conception architecturale n’est pas liée ou fondamentalement basée sur une technologie, un cadre, un langage de programmation ou de script, un IDE ou une méthodologie de développement. Tous ces éléments viennent plus tard dans le processus afin d’aider à construire l’architecture, mais ils ne sont pas le point central. Ils ne doivent pas être inclus dans les diagrammes, mais énoncés dans la description de l’architecture, y compris la justification autour de leur choix.

Mélanger des éléments d’exécution et statiques dans le même diagramme

• Les éléments d’exécution (par exemple, les threads, les processus, les machines virtuelles, les conteneurs, les services, les pare-feu, les dépôts de données, etc.) ne sont pas présents au moment de la compilation et il est recommandé d’éviter de mélanger ces éléments avec les éléments statiques (par exemple, les composants, les packages, les classes) dans le même diagramme. Il existe des types de diagrammes dédiés (par exemple, diagramme de concurrence, diagramme de déploiement) qui sont principalement axés sur les éléments d’exécution et il est important de distinguer ces deux catégories d’éléments et d’éviter de les mélanger autant que possible.

Faire des hypothèses comme « Je vais décrire verbalement ceci », et « Je l’expliquerai plus tard »

• Tout ce qui n’est pas décrit par le diagramme lui-même est absent, et il n’y a pas de place pour fournir des détails verbaux pour compléter un diagramme. Pourquoi ? Parce que toutes les explications mentionnées oralement mais non capturées dans le diagramme sont perdues, et plus tard, lorsque certaines parties prenantes (par exemple, le développeur, l’architecte) liront le diagramme, elles ne seront pas au courant de ces explications. Essayez d’inclure tous les détails nécessaires dans un diagramme pour éviter tout besoin d’éclaircissements supplémentaires.

Niveaux de détails conflictuels ou abstractions mixtes

• L’ajout d’éléments liés à différents niveaux d’abstraction dans le même diagramme pourrait entrer en conflit, car ils sont vus de différentes perspectives. Par exemple, l’ajout de composants à un diagramme de contexte architectural ou de classes à un diagramme de déploiement pourrait faire diverger l’objectif du diagramme lui-même. Lorsque vous créez un diagramme, essayez de vous en tenir au même niveau d’abstraction.

Des diagrammes encombrés ou trop vagues essayant de montrer un niveau de détail trop élevé ou insuffisant

• « Tout doit être rendu aussi simple que possible, mais pas plus simple » est une citation bien connue appartenant à Albert Einstein. Ceci est également valable pour les diagrammes d’architecture ; le niveau et la granularité des informations capturées doivent être choisis de manière significative. Ce n’est pas une chose facile ; cela dépend du modèle architectural utilisé, de l’expérience de l’architecte et de la complexité du système.

Lignes directrices à suivre lors de la création de diagrammes architecturaux

A part les pièges ci-dessus, qui doivent faire partie d’une liste de contrôle préalable afin de les éviter, il existe également des lignes directrices générales sur la façon de créer correctement des diagrammes :

Choisir le nombre optimal de diagrammes

• Comme l’a dit Philippe Kruchten, « l’architecture est une bête complexe. L’utilisation d’un seul schéma pour représenter l’architecture aboutit à un désordre sémantique inintelligible. » Pour documenter les systèmes modernes, nous ne pouvons pas nous retrouver avec un seul type de diagramme, mais lors de la création de diagrammes d’architecture, il n’est pas toujours évident de savoir quels diagrammes choisir et combien en créer. Il y a de multiples facteurs à prendre en considération avant de prendre une décision ; par exemple, la nature et la complexité de l’architecture, les compétences et l’expérience de l’architecte logiciel, le temps disponible, la quantité de travail nécessaire pour les maintenir, et ce qui a du sens ou est utile pour répondre aux préoccupations des parties prenantes. Par exemple, un ingénieur réseau voudra probablement voir un modèle de réseau explicite comprenant les hôtes, les ports de communication et les protocoles ; un administrateur de base de données se préoccupe de la manière dont le système manipule, gère et distribue les données, etc. Sur la base de tous ces aspects, il est recommandé de choisir le nombre optimal de diagrammes, quel que soit ce nombre.
• S’il n’y a pas assez de diagrammes (par exemple, une sous-documentation), des parties de l’architecture pourraient être cachées ou non documentées ; d’un autre côté, s’il y en a trop (par exemple. sur-documentation), l’effort nécessaire pour les garder cohérents, mis à jour et non fragmentés pourrait considérablement augmenter.

Maintenir la cohérence structurelle et sémantique entre les diagrammes

• Chaque diagramme devrait être cohérent avec les autres en termes de boîtes, de formes, de frontières, de lignes, de couleurs, etc. L’aspect structurel doit être le même et chaque partie prenante ne doit avoir aucune difficulté à comprendre les diagrammes créés par différents développeurs au sein d’une équipe. Idéalement, tenez-vous en à un outil de diagramme commun et réutilisez-le dans tous les projets.
• Du point de vue sémantique, tous ces diagrammes doivent être périodiquement synchronisés aux dernières modifications du code et entre eux, car un changement dans un diagramme peut avoir un impact sur les autres. Ce processus peut être déclenché manuellement ou automatiquement à l’aide d’un outil de modélisation. Ce dernier est le mécanisme préféré mais cela dépend de chaque projet. Dans tous les cas, l’idée est de maintenir la cohérence entre les diagrammes et le code, indépendamment de la méthode ou de l’outil. Simon Brown a dit « les diagrammes ne sont pas utiles pour l’amélioration de l’architecture s’ils ne sont pas connectés au code », ce qui souligne l’idée de cohérence sémantique.

Prévenir la fragmentation des diagrammes

• Avoir de multiples diagrammes pourrait rendre la description architecturale difficile à comprendre mais aussi un effort significatif pour les maintenir. Comme effet secondaire, une fragmentation pourrait apparaître (par exemple, deux ou plusieurs diagrammes illustrent le même attribut de qualité – performance, évolutivité, etc. – mais chacun d’eux est individuellement incomplet). Dans de tels cas, il est recommandé de supprimer les diagrammes qui ne reflètent pas les attributs de qualité pertinents (liés aux exigences significatives sur le plan architectural) ou, encore mieux, de fusionner les diagrammes (par exemple, la concurrence et le déploiement).

Garder la traçabilité entre les diagrammes

• Pouvoir vérifier l’historique, faire des comparaisons entre différentes versions de diagrammes plus revenir facilement à une version précédente est également important. Utiliser un outil de modélisation qui ne permet pas cela pourrait être un obstacle. Les dernières tendances du secteur reposent sur l’utilisation d’un langage simple et intuitif en texte clair pour générer les diagrammes à partir de celui-ci, ce qui semble résoudre le problème de la traçabilité. Un autre avantage d’une telle approche est qu’elle assure implicitement une cohérence structurelle homogène entre les diagrammes.

Ajouter des légendes à côté des diagrammes architecturaux

• Si vous ne suivez pas un langage de description architectural standard (par exemple UML, ArchiMate), détaillez chaque élément du diagramme dans la légende (par exemple, les boîtes, les formes, les bordures, les lignes, les couleurs, les acronymes, etc).
• Si ce n’est pas le cas, dans la légende, il suffit d’ajouter le langage de description architectural comme clé et il n’y a pas besoin d’explications supplémentaires, puisque chaque lecteur suivra sur les spécificités de ce langage pour comprendre le diagramme.

Le langage de description architectural (par exemple UML, ArchiMate, etc.) fait-il une différence ?

Il y a beaucoup d’opinions concernant quel est le bon langage de description à adopter dans le projet. Certaines personnes pourraient soutenir que UML est rigide et pas assez flexible pour modéliser la conception architecturale, un point de vue avec lequel je suis d’accord. Néanmoins, dans certains cas, il peut être plus que suffisant pour documenter les principes fondamentaux d’une architecture sans s’appuyer sur les fonctions d’extensibilité d’UML comme les profils et les stéréotypes. En examinant d’autres langages de description, nous pouvons constater qu’ArchiMate est plus puissant et plus adapté à la modélisation des systèmes d’entreprise par rapport à UML ; il y a aussi BPMN qui est particulièrement ciblé sur les processus métier, etc. Les comparaisons pourraient continuer, mais je n’ai pas l’intention de faire un examen approfondi à travers eux, puisque ce n’est pas le but de cet article.

Avoir un langage de description architectural assez complet et flexible est un grand pas en avant et cela devrait être un critère solide pour le choisir. Mais de mon point de vue, la véritable cause réside ailleurs et est liée au fait que la documentation architecturale n’est pas créée du tout. Les gens trouvent souvent que sa création est ennuyeuse, inutile ou sans intérêt. Le nombre de projets logiciels sans documentation ou avec une documentation inadéquate est énorme. Je ne pense pas que les gens créent ou participent intensivement à la création de diagrammes architecturaux en utilisant un langage de description inapproprié, et s’ils devaient les remplacer par un meilleur langage, les résultats seraient très différents. Non, les gens ne créent aucune documentation architecturale (y compris des diagrammes architecturaux) et, pire encore, la plupart d’entre eux n’ont aucune idée de la façon de la créer correctement. Ce sont les choses que nous devons aborder en premier lieu – comprendre pourquoi la documentation est importante et comment la créer correctement (en formant les ingénieurs logiciels) ; ensuite, la sélection des outils appropriés vient naturellement.

Comment maintenir les diagrammes à jour au fur et à mesure que le système est développé, et que les changements à l’architecture se matérialisent

Il existe quelques approches pour maintenir les diagrammes à jour ; ci-dessous, j’en exprimerai trois. La première option, et la plus simple, serait de générer automatiquement des diagrammes à partir du code source, qui est la vérité terrain. Cela garantit qu’ils sont tous cohérents avec le code. Malheureusement, avec les outils existants, ce n’est pas encore tout à fait possible (du moins à ma connaissance), puisque les outils actuels ne peuvent créer aucun type de diagramme précis et significatif uniquement à partir du code source, sans une intervention manuelle importante. Len Bass a dit « l’environnement de développement idéal est celui pour lequel la documentation est disponible essentiellement gratuitement en appuyant sur un bouton », générant implicitement automatiquement les diagrammes, mais nous n’avons pas atteint ce point.

La deuxième approche serait de concevoir d’abord les diagrammes en utilisant un outil dédié qui génère ensuite les squelettes de code source (par exemple, les composants/packages avec les frontières, les API) utilisés plus tard par les développeurs pour remplir le code. De cette façon, chaque changement dans l’architecture doit être déclenché à partir du diagramme lui-même qui pourrait automatiquement régénérer ou mettre à jour le squelette de code.

Le dernier cas implique la mise à jour manuelle des diagrammes chaque fois qu’une nouvelle fonctionnalité – qui a un impact sur la conception architecturale – est mise en œuvre. Pour être sûr que tous les changements de code sont reflétés dans les diagrammes, il est recommandé que la mise à jour des diagrammes à faire partie de la définition de fait dans le processus de développement. Ce scénario est moins recommandé car il pourrait facilement causer des diagrammes périmés ou incohérents (par exemple, les développeurs oublient souvent ou ne sont pas d’humeur à mettre à jour les diagrammes) et malheureusement cela se produit encore dans une majorité des projets.

En tenant compte des outils existants, ma recommandation est d’avoir un mélange ; de mélanger automatiquement et manuellement créer des diagrammes. Par exemple, essayez de générer automatiquement des diagrammes, qui peuvent être raisonnablement rendus par des outils basés sur le code source sans trop de bruit (par exemple, des informations trop encombrées ou sans signification). Dans cette catégorie, nous pouvons inclure soit des diagrammes avec un haut degré de volatilité (par exemple, plus enclins à des changements de développement fréquents, ayant généralement une abstraction plus faible) ou, au contraire, des diagrammes statiques. Certains de ces diagrammes peuvent faire référence à des diagrammes de contexte, des diagrammes d’architecture de référence, des diagrammes de paquetage, des diagrammes de classe, des diagrammes d’entité, etc. Néanmoins, dans certains cas, il n’est pas évident, en se basant uniquement sur le code source, de savoir comment le système répond à certains attributs de qualité (par exemple, la disponibilité, l’évolutivité, les performances), et la création automatique de diagrammes n’est donc pas une option suffisante. Elle doit être complétée par des diagrammes modélisés manuellement. Certains exemples de ces diagrammes comprennent les diagrammes de séquence, les diagrammes d’état, les diagrammes de concurrence, les diagrammes de déploiement, les diagrammes opérationnels, etc.

Quelles complications (ou simplifications) émergent pour les diagrammes architecturaux lorsqu’on traite des architectures modernes (par ex.p. ex. les microservices)?

Les microservices ou tout autre style architectural moderne (p. ex. serverless, event driven) ne font que piloter la structure du système, la façon dont les composants communiquent entre eux (p. ex. les relations entre eux) et les principes qui les régissent. Personnellement, je ne pense pas que le style architectural doive changer le raisonnement ou les concepts entourant la création des diagrammes (et implicitement la description architecturale), ni ce qu’ils doivent capturer. Néanmoins, lorsque nous parlons d’architectures de systèmes modernes, ayant généralement des niveaux de complexité plus élevés par rapport aux systèmes anciens et classiques (par exemple, monolithique), ils ont certainement un impact sur la description architecturale et implicitement sur les diagrammes, dans le sens où il y a de multiples considérations à prendre en compte. Ces considérations peuvent concerner la compréhension du nombre de composants distribués (par exemple, les microservices distribués), le type de chaque composant, la façon dont les composants communiquent entre eux (par exemple, les frontières, les API, les messages), leur cycle de vie et qui est propriétaire de chaque composant.

En tenant compte de tout cela, les vues capturant la décomposition du système, le développement, le déploiement et l’opérabilité devraient être considérées par défaut. Imaginez un système avec un nombre impressionnant de micro-services, par exemple ; dans un tel cas, le nombre de diagrammes pourrait augmenter de manière significative car chaque microservice pourrait finir par avoir son propre ensemble de diagrammes. Les problèmes de cohérence (par exemple, la modification de l’API d’un service a des répercussions sur les autres services X, ce qui nécessite la mise à jour de tous les diagrammes concernés), de fragmentation (par exemple, la haute disponibilité ou les performances entre les services distribués ne sont pas regroupées dans un seul diagramme) ou les problèmes transversaux (par exemple, qui est chargé d’illustrer, de manière consolidée, des aspects tels que la surveillance ou la sécurité dans l’ensemble des éléments du système) peuvent être difficiles à gérer. En plus de cela, il pourrait y avoir des défis liés à la coexistence et à la collaboration des équipes pendant le développement du projet, et même après, afin de le maintenir.

Pour résumer, les systèmes modernes avec des architectures complexes pourraient apporter des préoccupations supplémentaires qui pourraient entraîner des complications même au niveau des diagrammes.

A propos de l’auteur

Ionut Balosin est un architecte logiciel et un formateur technique indépendant. Il intervient régulièrement lors de conférences et de meetups sur le développement de logiciels dans le monde entier, délivrant des présentations, des cours de formation et des ateliers. Pour plus de détails, veuillez consulter son site Web.