Spécification technique de « Architecture.md (2021) »

Recommandations pour la rédaction de ARCHITECTURE.md

• Il est fortement recommandé aux mainteneurs de projets open source d’ajouter un document ARCHITECTURE à côté de README et CONTRIBUTING.
• Ce document décrit l’architecture de haut niveau du projet et, comme il doit être lu par les contributeurs réguliers, il vaut mieux le garder court.
• Le document ARCHITECTURE ne devrait contenir que des éléments qui ne changent pas souvent, et il est préférable de le relire quelques fois par an plutôt que d’essayer de le synchroniser avec le code.

Objectif et importance du document

• La connaissance de l’architecture physique du projet est la principale différence entre les contributeurs ordinaires et les développeurs principaux.
• Lorsqu’on ne connaît pas bien le projet, il faut deux fois plus de temps pour écrire un patch, et dix fois plus de temps pour déterminer où le code doit être modifié.
• Le fichier ARCHITECTURE est un moyen efficace de combler cet écart, tout en offrant une occasion de réfléchir à la structure du projet.

Structure du document

• Il doit commencer par une vue d’ensemble apportant un angle nouveau sur le problème, puis fournir une carte du code détaillée expliquant les relations entre les modules.
• Il faut mentionner les fichiers, modules et types importants, mais encourager la recherche par nom plutôt que les liens directs, afin d’éviter la maintenance de ces liens.
• Il faut signaler explicitement les invariants architecturaux et souligner les frontières entre les couches.

Invariants architecturaux et frontières

• Les invariants importants sont souvent exprimés par l’absence de quelque chose, et il est difficile de les identifier en lisant simplement le code.
• Les frontières entre les couches ou les systèmes contiennent implicitement des informations sur l’implémentation du système et contraignent toutes les implémentations possibles.

Préoccupations transversales

• Une fois la carte du code terminée, il faut ajouter une section distincte sur les préoccupations transversales.
• Un bon exemple de document ARCHITECTURE est le architecture.md de rust-analyzer.

Avis de GN⁺ :

• Le document ARCHITECTURE joue un rôle important pour aider à comprendre le projet et permettre aux nouveaux contributeurs de se familiariser rapidement avec la base de code.
• Ce document clarifie la structure du projet et met en avant les principes architecturaux et les frontières importantes afin d’aider les développeurs à mieux comprendre le système.
• Dans la communauté open source, l’adoption d’un document ARCHITECTURE peut contribuer à la croissance durable et à la maintenance du projet, ce qui en fait une approche très utile et intéressante pour les développeurs.

[GN⁺]

Avis Hacker News

• Si vous gérez un projet open source et que sa base de code fait entre 10k et 200k lignes, je recommande vivement d’ajouter un document ARCHITECTURE.

  • L’idée est bonne, mais je pense qu’on peut inclure l’architecture dans le README quelle que soit la taille du dépôt. Par exemple, je place volontairement un diagramme de séquence Mermaid dans le README principal afin que tous les utilisateurs puissent comprendre le workflow.

• Cette approche est excellente comme modèle à faible maintenance pour les projets open source avec beaucoup de contributeurs ponctuels. Pour les projets avec des ingénieurs dédiés, il faut envisager les ADR. Cela demande davantage de maintenance, mais consigner le « pourquoi » et les « alternatives envisagées » est très utile lors d’une reconstruction.

• J’ai expérimenté quelque chose de similaire il y a quelques années sur l’un de mes gros projets annexes :

  • En haut de chaque fichier, il y avait un arbre de liens vers d’autres fichiers ARCHITECTURE.md.

• Tous les IDE affichent la structure des dossiers d’un projet à gauche sous forme d’arborescence de répertoires standard. Existe-t-il un IDE qui permette d’explorer un projet à partir d’un graphe de dépendances ?

• Il faut faire attention à ne pas généraliser à tous les projets logiciels ce que l’auteur écrit ici. Pour les gros projets open source avec beaucoup de contributeurs qui ont peu de contexte, maintenir ce genre de document a de la valeur. Mais dans les petits projets professionnels, tous les documents rédigés par les développeurs que j’ai vus finissent par ne plus être entretenus.

• Plus un document est court, moins il risque d’être invalidé par des changements futurs. C’est la règle principale d’un document ARCHITECTURE — ne spécifiez que ce qui a peu de chances de changer souvent. N’essayez pas de le synchroniser avec le code.

  • Les interfaces ont moins de chances de changer et c’est [plus difficile !] (Parnas, critères utilisés pour décomposer les systèmes en modules).

• Dans tous les projets, lors de l’onboarding, je montre un diagramme d’architecture et une brève explication de ses composants.

  • Je suis désormais surpris de voir à quel point c’est rare dans l’open source.

• C’est une pratique très utile. Beaucoup de projets ont quelques fichiers clés (ou packages/modules/etc.) où se produisent la plupart des changements. Si on aide les nouveaux contributeurs (ou ceux qui reviennent après longtemps) à se familiariser rapidement avec eux, on peut réduire considérablement le temps nécessaire pour se mettre à contribuer au projet.

• J’ai toujours été fan de ces petits standards de documentation / diagrammes sous forme de code :

  • développement piloté par le README
  • ARCHITECTURE.md
  • ADR
  • arc42
  • C4
  • etc.
  • Maintenant, je mets un vault Obsidian dans le dossier /docs du dépôt git.
  • Au lieu d’utiliser le standard de quelqu’un d’autre, j’organise et refactorise la documentation comme je gère mes notes personnelles dans Obsidian.
  • J’ai essayé d’utiliser un sous-ensemble commun de Markdown qui fonctionne à la fois sur GitHub (GFM) et dans Obsidian, mais j’ai fini par abandonner et utiliser le Markdown d’Obsidian et ses fonctionnalités dédiées.
  • Obsidian intègre Mermaid et LaTeX, et il existe un plugin pour PlantUML.
  • Pour les illustrations/diagrammes visuels, Canvas, DrawIO et Excalidraw sont intégrés.

• Déjà discuté à l’époque :

  • Architecture.md - fév. 2021 (153 commentaires)