arc42 et autres modèles de documentation

Ce qu’est arc42

arc42 est un modèle gratuit pour décrire et communiquer l’architecture logicielle, créé par Gernot Starke et Peter Hruschka et utilisé en pratique depuis 2005. Il est publié sous licence Creative Commons Attribution-ShareAlike, dans plus d’une douzaine de langues et dans des formats comme AsciiDoc, Markdown et Word, avec une version plain (vierge) et une version qui intègre des textes d’aide. Il est particulièrement répandu dans les pays germanophones et dans les formations iSAQB, mais il est utilisé dans le monde entier.

arc42 n’est délibérément ni une méthode ni une notation. Il ne vous dit pas comment concevoir, et il n’impose ni UML, ni C4, ni aucun autre style de diagramme. C’est un ensemble de douze tiroirs étiquetés : pour chaque type d’information architecturale, il indique où la ranger, pour que chaque lecteur sache où chercher et que chaque rédacteur sache ce qui manque. Ses auteurs affirment clairement que chaque section est facultative ; un petit système peut remplir quatre sections en quelques pages, un grand peut remplir les douze sur de nombreuses pages.

Le modèle s’appuie sur des idées vues plus tôt dans ce chapitre. Ses trois vues (blocs de construction, exécution et déploiement) correspondent étroitement aux catégories modules, composants et connecteurs, et allocation du SEI, ainsi qu’aux vues de développement, de processus et physique de Kruchten, présentées dans vues et points de vue. Sa section consacrée aux décisions est l’endroit où vont les enregistrements de décision d’architecture, et sa section consacrée à la qualité est l’endroit où vont les scénarios d’attributs de qualité du chapitre 2.

Les douze sections

Le diagramme regroupe les sections selon la question à laquelle elles répondent. Les sections 1 à 3 fixent les objectifs et les limites : à quoi sert le système, ce qui limite la solution et où le système s’arrête. La section 4 énonce les idées fondamentales de la solution, et les sections 8 et 9 contiennent les principes et les décisions qui s’appliquent à l’ensemble de celle-ci. Les sections 5 à 7 montrent la structure sous trois angles. Les sections 10 à 12 rendent explicites la qualité, les risques et le vocabulaire.

Utiliser arc42 avec légèreté

La façon la plus courante d’échouer avec arc42 est de le traiter comme un formulaire à remplir : douze intitulés sont créés, chacun est rempli avec quelque chose, et le résultat est long, générique et jamais lu. Les conseils du modèle lui-même vont dans l’autre sens. La FAQ d’arc42 indique qu’il n’existe pas de règle générale pour le minimum, car il dépend de la criticité, de la taille, de la complexité et du risque, mais suggère que même une description minimale contienne trois à cinq exigences de qualité centrales sous forme de scénarios, le contexte et les interfaces externes, une brève stratégie de solution, la vue des blocs de construction de niveau 1 et les concepts transversaux les plus importants.

Quatre habitudes permettent de garder arc42 léger. Supprimez les sections vides ou signalez-les délibérément (Déploiement : plateforme managée unique ; voir le dépôt d’infrastructure), pour que le lecteur sache que le vide est intentionnel. Faites des liens plutôt que des copies : les exigences vivent dans le backlog, les décisions dans le dossier des ADR, le déploiement dans l’infrastructure en tant que code ; arc42 renvoie vers eux. Préférez des diagrammes accompagnés de courts tableaux d’éléments à des pages de prose. Écrivez pour les questions du prochain lecteur, pas pour l’exhaustivité : si personne ne posera de question sur le comportement à l’exécution des écrans d’administration, ne le décrivez pas.

arc42 se combine bien avec le modèle C4. Une association courante consiste à placer un diagramme de contexte système C4 dans la section 3, un diagramme de conteneurs comme niveau 1 de la vue des blocs de construction dans la section 5, avec des diagrammes de composants comme niveau 2, et un diagramme de déploiement C4 dans la section 7. Conservée sous forme de diagrammes en tant que code dans le même dépôt que le texte arc42, toute la description peut être versionnée et revue comme du code.

Exemple commenté : arc42 allégé pour la plateforme de livraison de repas

La page ci-dessous est une description arc42 allégée complète de la plateforme de livraison de repas utilisée tout au long de ce chapitre. Elle tient sur une page imprimée plus le diagramme de contexte, et pourtant elle répond aux questions qu’un nouvel ingénieur, un responsable des opérations ou un auditeur poserait en premier, et elle indique où se trouvent les détails.

Autres modèles

Le modèle Views and Beyond du SEI. Le Software Engineering Institute publie un modèle de documentation qui suit l’ouvrage Documenting Software Architectures: Views and Beyond de Paul Clements et de ses collègues. Son niveau supérieur comporte six parties : une feuille de route et une vue d’ensemble de la documentation, le contexte de l’architecture, les vues, la mise en correspondance des vues, les documents de référence, et un glossaire avec les acronymes. Chaque vue est documentée de la même manière, avec une présentation principale, un catalogue des éléments, un diagramme de contexte, un guide de variabilité et la justification (décrits dans l’encadré « Pour aller plus loin » de la section 4.2). Il est plus complet qu’arc42 et convient aux systèmes de grande taille, à longue durée de vie ou spécifiés par contrat, où chaque vue doit être complète et faire l’objet de renvois croisés ; sa mise en correspondance des vues est un point fort qu’arc42 laisse implicite.

IEEE 1016. La norme IEEE Std 1016-2009, Software Design Descriptions, spécifie le contenu et l’organisation d’une description de la conception logicielle (SDD), le document de conception détaillée traditionnellement exigé dans la défense, l’aérospatiale et d’autres projets régis par des contrats. Elle a emprunté les concepts de partie prenante, de préoccupation, de point de vue et de vue à l’IEEE 1471 (le prédécesseur de la 42010) et liste des points de vue de conception comme le contexte, la composition, le point de vue logique, les dépendances, l’information, les interfaces, l’interaction, la dynamique des états, les algorithmes et les ressources. L’IEEE l’a placée au statut inactive-reserved (inactive, réservée) en 2020, mais elle est toujours citée dans des contrats et dans l’enseignement, et d’anciens programmes livrent encore des SDD sous sa forme. Elle est plus proche de la conception détaillée que de l’architecture.

Les documents de conception et les RFC, utilisés par de nombreuses organisations d’ingénierie, sont un autre type de modèle : une proposition pour un changement unique plutôt que la description d’un système entier. Ils sont traités deux sections plus loin, dans communiquer l’architecture.

Conformité à l’ISO/IEC/IEEE 42010

L’ISO/IEC/IEEE 42010:2022 fixe des exigences pour les descriptions d’architecture et pour les cadres de description d’architecture (ADF) : des conventions établies, comme arc42 ou l’approche Views and Beyond, pour produire des descriptions dans une communauté donnée. Elle ne prescrit ni modèle, ni notation, ni processus. Une description est conforme lorsqu’elle contient les informations que la norme exige, quel que soit le modèle qui les organise.

Dans les grandes lignes, cela signifie identifier le système décrit et son environnement, identifier les parties prenantes et leurs préoccupations, indiquer quels points de vue sont utilisés et quelles préoccupations chacun encadre, fournir des vues qui suivent ces points de vue, consigner les correspondances (comment les éléments de différentes vues sont liés) et consigner la justification des décisions clés. arc42 ne revendique pas la conformité d’emblée, et les descriptions arc42 brutes manquent souvent d’un lien explicite entre chaque préoccupation et la vue qui la traite. Les lacunes sont minimes et faciles à combler, comme le montre le tableau. La plupart des équipes n’ont pas besoin d’une conformité formelle ; celles des secteurs réglementés ou liées par un contrat en ont parfois besoin, et il est rassurant qu’un modèle léger puisse satisfaire la norme avec quelques ajouts.