2.14 Structure des projets et des dépôts

Vue d’ensemble et motivation

La structure des projets et des dépôts est l’organisation physique d’une base de code : les dossiers, les fichiers et les conventions de nommage qui décident où vit chaque chose. Un dépôt (souvent appelé « repo ») est le conteneur sous contrôle de version qui héberge les fichiers d’un projet et leur historique. Un projet, parfois appelé solution quand il regroupe plusieurs composants liés, est l’unité logique de logiciel que vous construisez. La structure est la carte que vous utilisez pour trouver, comprendre et modifier ce logiciel.

Dans une petite équipe, une seule personne peut garder toute la disposition en tête. Dans une grande équipe, avec des centaines ou des milliers d’ingénieurs, des mouvements fréquents entre équipes, et des prestataires qui arrivent et repartent, chaque dépôt organisé différemment facture une nouvelle taxe cognitive. Quand vous ouvrez un dépôt inconnu, vous devriez pouvoir deviner où vivent la source, les tests, la documentation et la configuration de déploiement, sans lire un manuel. Quand chaque dépôt répond à ces questions de la même façon, la mobilité est bon marché et l’intégration est rapide. Quand chaque dépôt est un flocon de neige unique, chaque changement de contexte se transforme en petit projet de recherche.

Dans les contextes d’entreprise et d’administration publique, une structure cohérente est aussi un enjeu de contrôle et d’assurance. Les auditeurs, les relecteurs de sécurité et les mainteneurs de long terme, travaillant souvent des années après le départ des auteurs originaux, doivent pouvoir localiser de façon fiable les documents de spécification, les fichiers de licence, les politiques de sécurité et les définitions de construction. Une disposition prévisible permet aussi à l’outillage automatisé (scanners, analyseurs de dépendances, vérifications de conformité) de fonctionner de la même façon à travers tout un portefeuille de systèmes. Ce chapitre traite donc la structure comme une convention que l’on décide une fois et que l’on applique partout. Il se rattache étroitement aux normes et au style de codage (chapitre 2.1), au contrôle de version et à la gestion des sources (chapitre 2.6), et à la documentation (chapitre 2.7).

Principes clés

Suivez le principe de moindre surprise : la disposition doit correspondre à ce qu’un ingénieur expérimenté attendrait, de sorte que rien n’a besoin d’être mémorisé.
La cohérence entre dépôts l’emporte sur l’astuce locale ; une structure suffisamment uniforme partout vaut plus que la structure parfaite à un seul endroit.
Le README est la porte d’entrée ; un nouvel arrivant devrait pouvoir s’orienter à partir de lui seul.
Rendez la structure auto-descriptive par le nommage, pour que les dossiers et les fichiers annoncent leur but.
Imposez la structure par l’échafaudage et les modèles, pas par la volonté et les commentaires de relecture.
Séparez les préoccupations physiquement : source, tests, documentation, construction et déploiement appartiennent à des endroits distincts et prévisibles.
Organisez les dépendances pour qu’elles circulent dans une seule direction, des noyaux stables vers les bords volatils.

Recommandations

Adopter une disposition de premier niveau cohérente

Définissez un ensemble standard de dossiers de premier niveau que chaque dépôt utilise là où c’est pertinent, et documentez à quoi chacun sert. Une convention courante et neutre vis-à-vis des fournisseurs comprend : un dossier source (souvent src) pour le code de production ; un dossier de tests (souvent test ou tests) pour les tests automatisés ; un dossier docs pour la documentation ; un dossier build pour les définitions et les sorties de construction ; un dossier deploy pour le déploiement et l’infrastructure en tant que code (définitions lisibles par machine des serveurs, réseaux et services, traitées au chapitre 8.2) ; un dossier scripts pour l’automatisation et l’outillage des développeurs ; un dossier examples pour des exemples exécutables ; et un dossier spec ou specification pour les exigences et les spécifications de conception. Tous les dépôts n’ont pas besoin de tous les dossiers, mais là où une préoccupation existe, elle doit vivre à l’endroit attendu sous le nom attendu.

Faire du README le point d’entrée

Exigez un fichier README à la racine du dépôt comme point de départ unique et canonique. Il devrait énoncer ce qu’est le projet, comment le construire et l’exécuter, comment lancer les tests, où trouver une documentation plus approfondie, qui en est propriétaire, et comment contribuer. Le README n’est pas l’ensemble de la documentation ; c’est l’index qui pointe vers le reste (chapitre 2.7). Traitez un README manquant ou obsolète comme un défaut, parce que c’est la première chose que lira chaque nouvel ingénieur, auditeur ou intégrateur.

Standardiser les fichiers d’éditeur et de configuration

Versionnez la configuration partagée d’éditeur et d’outillage dans le dépôt pour que chaque contributeur obtienne automatiquement un comportement cohérent. Un fichier .editorconfig (un fichier simple, indépendant de l’éditeur, qui définit les règles d’espaces, d’indentation et de fin de ligne) garde le formatage de base uniforme entre différents éditeurs et systèmes d’exploitation. Ajoutez un fichier d’exclusion pour le système de contrôle de version (afin que les sorties de construction et les artefacts locaux ne soient jamais versionnés), ainsi que les configurations partagées de formateur et de linter décrites au chapitre 2.1. Ces fichiers rendent les conventions du dépôt actives, pas seulement documentées.

Définir des conventions de nommage et de dossiers

Mettez-vous d’accord sur des conventions de nommage des dossiers et des fichiers (casse, séparateurs, singulier contre pluriel, et suffixes requis comme ceux qui marquent les tests) et appliquez-les uniformément. Les noms devraient révéler l’intention et correspondre au vocabulaire du domaine utilisé ailleurs dans l’organisation. L’objectif est simple : un chemin doit communiquer du sens, de sorte que lire un nom de dossier ou de fichier vous dise ce qu’il contient sans l’ouvrir.

Organiser délibérément les couches et les dépendances

Structurez la base de code pour que ses couches architecturales apparaissent dans la disposition des dossiers, et pour que les dépendances circulent dans une seule direction sensée. La politique de haut niveau ne devrait pas dépendre du détail de bas niveau. Le code partagé et stable devrait se trouver là où de nombreux modules peuvent l’atteindre sans créer de cycles. Quand vous rendez la stratification physique, reflétée dans l’arborescence de répertoires, les ingénieurs sont plus enclins à la respecter, et les violations sont plus faciles à repérer en relecture et par des vérifications automatisées de dépendances.

Imposer la structure par l’échafaudage et les modèles

Fournissez un échafaudage, la génération automatisée d’un projet de départ, pour que les nouveaux dépôts commencent déjà corrects. Un modèle ou cookiecutter (un squelette de projet paramétré qui génère un dépôt prêt à l’emploi à partir des réponses à quelques questions) encode la disposition standard, le README, les fichiers de configuration et la configuration d’intégration continue en un seul endroit. Quand les ingénieurs créent de nouveaux services à partir d’un modèle partagé, la cohérence devient la valeur par défaut au lieu d’une aspiration, et les améliorations du modèle se répercutent sur les futurs projets.

Garder la structure cohérente à travers de nombreux dépôts à grande échelle

Traitez la disposition elle-même comme une norme gouvernée : maintenue centralement comme toute autre norme d’ingénierie (chapitre 1.7), et versionnée comme du code (chapitre 2.6). Publiez-la, fournissez les modèles qui l’implémentent, et n’autorisez les écarts que par un processus d’exception documenté, pour que « la norme » garde son sens. À l’échelle d’un portefeuille, presque toute la valeur de la structure vient de son uniformité à travers les dépôts, donc la dérive est le principal risque à gérer.

Laisser la structure éclairer le choix entre monorepo et multi-dépôts

Reliez la structure à la décision de frontière de dépôt traitée au chapitre 2.6. Un monorepo (un seul dépôt hébergeant de nombreux projets) a besoin d’une convention interne claire pour séparer les projets et leur code partagé, afin que l’arbre unique reste navigable. Une approche multi-dépôts (de nombreux petits dépôts, un par projet ou service) a besoin d’une forte cohérence inter-dépôts, pour que chaque dépôt paraisse familier même s’il est autonome. Dans les deux cas, une structure documentée et modélisée est ce qui garde la navigation prévisible. Le choix de frontière change où vous appliquez la convention, pas si vous en avez besoin.

Compromis : avantages et inconvénients

Choix	Avantages	Inconvénients
Disposition standard stricte à l’échelle de l’organisation	Familiarité instantanée ; ingénieurs mobiles ; outillage uniforme	Adéquation occasionnellement médiocre pour des projets inhabituels ; nécessite une gouvernance
Liberté de disposition par équipe	Optimisation locale ; forte autonomie	Fragmentation ; changements de contexte coûteux ; outillage incohérent
Échafaudage et modèles	Dépôts corrects par défaut ; les changements se propagent	Maintenance des modèles ; risque de dérive des dépôts générés
Hiérarchie de dossiers profonde et stratifiée	Structure explicite ; frontières claires	Surcharge de navigation ; chemins longs ; risque de sur-ingénierie
Disposition plate et peu profonde	Facile à parcourir ; peu de cérémonie	Séparation médiocre ; s’effondre à mesure que le projet grandit

Le compromis dominant est l’uniformité contre l’autonomie. Une disposition standard unique élimine la friction pour les nombreux ingénieurs qui se déplacent entre bases de code, au prix du projet occasionnel dont les besoins n’épousent pas bien le moule. Dans une grande organisation, le gain collectif de la familiarité l’emporte presque toujours sur cette perte locale. C’est pourquoi la posture recommandée est une norme par défaut forte plus un chemin d’exception documenté (chapitre 1.7), plutôt qu’une uniformité rigide ou une liberté non gérée. Un compromis secondaire est la profondeur contre la simplicité : assez de structure pour séparer les vraies préoccupations, mais pas au point que naviguer se transforme en randonnée à travers des dossiers vides.

Questions à discuter avec votre équipe

Quand un ingénieur se déplace vers un de nos dépôts inconnu, combien de temps avant qu’il puisse trouver les tests, la configuration de déploiement et le propriétaire ? C’est la taxe de navigation que la structure existe pour éliminer, et à l’échelle d’un portefeuille elle est payée des milliers de fois par an en petits incréments qui s’additionnent en pertes sérieuses de temps d’ingénierie. Le principe de moindre surprise dit qu’un ingénieur expérimenté devrait pouvoir deviner où vivent la source, les tests, la documentation et le déploiement sans lire un manuel, donc le test honnête est de savoir si cette supposition réussit à travers vos dépôts. Apportez un vrai chiffre à la réunion : chronométrez-vous en vous orientant dans deux ou trois dépôts internes inconnus, ou tirez des données d’intégration sur le temps que mettent les nouveaux arrivants à faire un premier changement. Si la réponse se mesure en jours de recherche plutôt qu’en minutes de reconnaissance, vous avez quantifié le coût des dépôts flocons de neige, et cela justifie l’investissement ponctuel dans une disposition standard partagée par chaque dépôt.
Nos couches architecturales apparaissent-elles dans l’arborescence de dossiers, ou des cycles de dépendance se cachent-ils dans une disposition plate ? La structure concerne plus que la trouvabilité : quand vous rendez la stratification physique, les ingénieurs la respectent et les relecteurs et les vérifications automatisées de dépendances peuvent repérer les violations, tandis qu’un tas plat laisse un couplage inapproprié et des cycles s’infiltrer inaperçus jusqu’à ce que le changement devienne dangereux. Sur un système grand et de longue durée, c’est ce qui empêche la politique de haut niveau de dépendre discrètement du détail de bas niveau, et c’est exactement le genre d’érosion bon marché à prévenir et coûteuse à défaire. Apportez votre graphe de dépendances ou faites une vérification rapide : y a-t-il des cycles, et quelque chose de stable dépend-il de quelque chose de volatil ? La réponse devrait vous pousser à refléter les couches dans les répertoires et à ajouter des vérifications automatisées de direction de dépendance, pour que les frontières soient visibles dans l’arbre et imposées dans le pipeline plutôt que de ne vivre que dans le modèle mental de quelqu’un.
Nos nouveaux dépôts démarrent-ils corrects à partir d’un modèle, ou comptons-nous sur une page de wiki et de bonnes intentions ? La structure imposée par l’échafaudage est la valeur par défaut ; la structure décrite dans un document dérive, parce que la réalité suit ce qui génère les dépôts, pas ce qu’une page dit qu’ils devraient être. Pour une grande organisation ou une organisation régulée, c’est aussi un enjeu d’assurance : quand chaque dépôt est généré à partir d’un modèle partagé, les scanners de sécurité, les analyseurs de dépendances et les auditeurs trouvent la licence, la politique de sécurité, la spécification et la définition de construction au même endroit à chaque fois, à travers les fournisseurs et à travers les années. Apportez la preuve : combien de vos dépôts récents ont été échafaudés à partir du modèle standard contre assemblés à la main, et jusqu’où ceux qui sont modélisés ont-ils dérivé depuis ? L’action est de faire du modèle le seul moyen facile de démarrer un dépôt, de le gouverner comme une norme versionnée avec un chemin d’exception documenté, et de détecter la dérive automatiquement, parce que l’uniformité est là où vit presque toute la valeur de la structure.
Avons-nous décidé si notre norme couvre un monorepo ou de nombreux dépôts séparés, et la même convention tient-elle réellement des deux côtés de cette frontière ? Le choix de frontière de dépôt change où vous appliquez la convention, pas si vous en avez besoin, et se tromper signifie soit un seul arbre géant que personne ne peut naviguer, soit un étalement de dépôts qui paraissent tous étrangers. Un monorepo a besoin d’une convention interne claire pour séparer les projets et leur code partagé afin que l’arbre unique reste navigable, tandis qu’une approche multi-dépôts a besoin d’une forte cohérence inter-dépôts pour que chaque dépôt autonome paraisse encore familier. Apportez l’inventaire actuel : combien de dépôts vous avez, comment le code partagé est séparé à l’intérieur de tout monorepo, et un test chronométré pour savoir si un ingénieur peut trouver un projet dans le grand arbre aussi vite qu’il en trouve un dans un dépôt autonome. Pour une grande entreprise ou un programme gouvernemental où différents fournisseurs livrent des dépôts séparés, décidez délibérément quelles parties de la convention sont universelles et lesquelles sont spécifiques à la frontière, parce que les auditeurs et l’outillage de plateforme doivent fonctionner de la même façon, que le code arrive comme un arbre ou comme cinquante.
Qui est propriétaire de notre norme de structure, et que se passe-t-il réellement quand un projet ne s’y adapte vraiment pas ? À l’échelle d’un portefeuille, presque toute la valeur de la structure vient de l’uniformité, donc les vrais risques sont une norme sans propriétaire qui pourrit et un chemin d’exception si vague que chaque équipe invente discrètement sa propre disposition. La tension est entre une uniformité rigide qui ne convient à aucun projet inhabituel et une liberté non gérée qui fragmente tout, et la réponse saine est une valeur par défaut forte plus un processus d’exception documenté et auditable, gouverné par un propriétaire nommé et versionné comme du code. Apportez la preuve : y a-t-il un propriétaire unique et responsable, un document de norme versionné avec un journal des changements, un journal des exceptions accordées et pourquoi, et un compte des écarts non documentés que vous pouvez trouver sur le terrain. Dans les contextes d’entreprise et d’administration publique, une exception que personne n’a consignée est une lacune de contrôle, donc liez chaque écart à une justification écrite et une date de révision, et assurez-vous que les contrats d’approvisionnement qui mandatent la disposition nomment aussi qui peut approuver les dérogations.
Notre README et nos fichiers de configuration versionnés rendent-ils nos conventions actives, ou sont-ils décoratifs ? Un README est la porte d’entrée et le fichier .editorconfig, le fichier d’exclusion et la configuration de linter versionnés sont ce qui rend les conventions auto-imposées, pourtant ce sont les premières choses à devenir obsolètes et les dernières que quiconque remarque jusqu’à ce qu’un auditeur ou un nouvel arrivant ne puisse pas faire construire le projet. La tension est entre un README allégé qui reste à jour et un README complet qui dérive, et entre faire confiance aux gens pour formater le code correctement et laisser une configuration partagée l’imposer automatiquement. Apportez un échantillon : tirez cinq dépôts et vérifiez combien de README énoncent réellement ce qu’est le projet, comment le construire, le tester et l’exécuter, et qui en est propriétaire, et combien portent les fichiers de configuration partagés plutôt que de compter sur les habitudes individuelles. Pour une grande organisation ou une organisation régulée, où intégrateurs, relecteurs de sécurité et mainteneurs de long terme lisent le README avant toute autre chose, traitez une porte d’entrée manquante ou obsolète comme un défaut avec un propriétaire, et vérifiez la présence des fichiers de configuration automatiquement pour que la conformité ne dépende pas de la bonne volonté.

Regard sectoriel

Jeune pousse. La rapidité l’emporte, donc mettez-vous d’accord sur une disposition simple et suffisamment plate pour votre premier dépôt (src, test, docs, scripts, un README rempli, un .editorconfig, et des fichiers d’exclusion) et enregistrez-la comme modèle léger le même après-midi. Générez le deuxième service à partir de là pour que les deux dépôts paraissent familiers et qu’un nouveau prestataire s’intègre en quelques heures plutôt que de rétro-concevoir un flocon de neige. Résistez aux hiérarchies profondes et à la gouvernance lourde dont vous n’avez pas encore besoin ; tout le retour ici est que deux fondateurs et un prestataire partagent une seule carte.

Petite entreprise. Sans spécialiste de plateforme et avec un budget serré, adoptez la disposition conventionnelle que votre langage ou framework suppose déjà plutôt que d’en inventer une, pour que l’outillage prêt à l’emploi et toute nouvelle recrue arrivent déjà formés dessus. Achetez de l’échafaudage (un générateur de framework ou un modèle cookiecutter) plutôt que de construire le vôtre, et dépensez votre effort rare à garder un README rempli à jour. Ce README est l’assurance la moins chère que vous ayez pour le jour où la seule personne qui connaissait la disposition s’en va.

Grande entreprise. À travers de nombreuses équipes et des centaines de dépôts, l’objectif est l’uniformité : publiez une norme de structure versionnée, générez chaque nouveau service à partir de modèles partagés, détectez la dérive automatiquement, et n’autorisez les écarts que par un processus d’exception documenté. Parce que chaque dépôt se ressemble, un ingénieur réaffecté à une nouvelle équipe est productif en quelques heures et les scanners de sécurité et de dépendances à l’échelle du portefeuille trouvent la licence, la politique de sécurité et la définition de construction au même endroit à chaque fois. Budgétez explicitement la maintenance des modèles et la détection de dérive, parce que cet entretien est ce qui garde la norme significative à l’échelle.

Gouvernement. L’approvisionnement, la transparence et la redevabilité de long terme façonnent la disposition, donc mandatez une structure commune dans les normes de livraison qui lient chaque fournisseur. Exigez un dossier specification reliant le code aux exigences approuvées, un fichier de licence et de politique de sécurité à la racine, et un dossier deploy hébergeant les définitions d’infrastructure en tant que code, pour que les auditeurs localisent les artefacts de conformité de la même façon dans chaque système. Parce que les prestataires de différents fournisseurs suivent tous une seule carte, la maintenance après la fin d’un contrat coûte bien moins cher, et le public gagne une piste défendable et inspectable, de l’exigence au code en fonctionnement.

Exemples

Jeune pousse. Une start-up de trois personnes se met d’accord sur une disposition standard simple pour son premier dépôt (src, test, docs, scripts, un README rempli, un .editorconfig, et des fichiers d’exclusion) et l’enregistre comme modèle léger. Quand elle lance son deuxième service un mois plus tard, elle le génère à partir de ce modèle, si bien que les deux dépôts paraissent déjà familiers et que le nouveau prestataire s’intègre en un après-midi. Elle résiste aux hiérarchies de dossiers profondes dont elle n’a pas encore besoin, gardant l’arbre assez plat pour être parcouru d’un coup d’œil. Le coût fut un après-midi de mise en place, et cela lui épargne l’étalement de flocons de neige qui ferait autrement de chaque futur dépôt un petit projet de recherche.

Grande entreprise. Un détaillant multinational exploite des centaines de services à travers plusieurs langages. Son équipe de plateforme publie une norme de structure de dépôt versionnée et un ensemble de modèles de projet qui l’implémentent. Chaque nouveau service est généré à partir d’un modèle, si bien qu’il arrive avec les dossiers standard src, test, docs, deploy et scripts, un README rempli, un .editorconfig, des fichiers d’exclusion, et un pipeline d’intégration continue fonctionnel. Parce que chaque dépôt se ressemble, un ingénieur réaffecté à une nouvelle équipe est productif en quelques heures, et les scanners de sécurité et de dépendances à l’échelle de l’organisation fonctionnent uniformément parce qu’ils trouvent toujours les fichiers là où ils les attendent.

Gouvernement. Une agence nationale modernisant des systèmes hérités mandate une disposition de dépôt commune dans le cadre de ses normes de livraison pour tous les fournisseurs. Chaque dépôt doit contenir un dossier specification reliant le code aux exigences approuvées, un README documenté, un fichier de licence et de politique de sécurité à la racine, et un dossier deploy hébergeant les définitions d’infrastructure en tant que code (chapitre 8.2). Parce que les prestataires de différents fournisseurs suivent tous la même structure, les auditeurs de l’agence peuvent localiser les artefacts de conformité de la même façon dans chaque système, et la maintenance de long terme après la fin d’un contrat coûte bien moins cher parce que les mainteneurs entrants connaissent déjà la carte.

Argumentaire économique : motivations, retour sur investissement et coût total de possession

Le coût d’adoption d’une norme de structure est principalement ponctuel : se mettre d’accord sur la disposition, construire les modèles et documenter la convention. Le coût récurrent est faible, concentré dans la maintenance des modèles et la gouvernance des exceptions. Le coût de ne pas avoir de norme est récurrent et cumulatif : chaque ingénieur qui ouvre un dépôt inconnu paie une taxe de navigation, chaque intégration se déroule plus lentement, et l’outillage automatisé doit être configuré dépôt par dépôt parce que rien n’est là où on l’attend. À travers une grande organisation, ces petites frictions se multiplient en pertes sérieuses de temps d’ingénierie.

Le retour se manifeste par une intégration plus rapide, une mobilité moins coûteuse entre équipes, un signal plus fort de l’outillage à l’échelle du portefeuille, et, dans les contextes régulés, un coût d’audit et de maintenance de long terme plus faible, parce que les artefacts sont toujours trouvables. Le coût total de possession (CTP, c’est-à-dire le coût complet sur le cycle de vie de construire, exploiter et maintenir un système) baisse le plus dans les systèmes de longue durée, où les mainteneurs qui bénéficient d’une structure prévisible ne sont généralement pas les auteurs qui l’ont créée. Pour faire valoir cela auprès de la direction, présentez la structure comme une norme à faible coût et à fort effet de levier qui améliore la productivité des développeurs et la préparation aux audits, et chiffrez le coût actuel de l’incohérence à l’aide des données de temps d’intégration et de l’effort dépensé à chercher des choses dans des dépôts inconnus.

Anti-patterns et pièges

Le dépôt flocon de neige : chaque dépôt organisé différemment, si bien que chacun doit être réappris à partir de zéro.
Le README manquant ou obsolète : pas de porte d’entrée, forçant les nouveaux arrivants à rétro-concevoir comment construire et exécuter le projet.
Structure par document, pas par modèle : une page de wiki décrit la disposition standard, mais rien ne la génère ni ne l’impose, si bien que la réalité s’en éloigne.
Dérive des modèles : les dépôts générés à partir d’un modèle divergent avec le temps et les améliorations du modèle ne les atteignent jamais.
Hiérarchie sur-ingénierée : des imbrications profondes de dossiers quasi vides qui ajoutent de la cérémonie sans aider la navigation.
Préoccupations mélangées : source, tests, sorties de construction et secrets entassés ensemble sans séparation claire.
Sorties de construction et artefacts locaux versionnés : des fichiers générés versionnés parce que les règles d’exclusion n’ont jamais été mises en place, polluant l’historique et les diffs.
Violations de couches cachées par une structure plate : pas de frontières physiques, si bien que les cycles de dépendance et le couplage inapproprié s’infiltrent inaperçus.

Modèle de maturité

Niveau 1 (Initier) : Chaque dépôt est organisé de façon ad hoc par ses auteurs, réagissant à ce dont le moment a besoin ; les dispositions varient largement ; les README sont manquants ou peu fiables ; les nouveaux arrivants doivent être guidés à travers chaque dépôt à la main.
Niveau 2 (Développer) : Des conventions de base existent de façon informelle et de nombreux dépôts se ressemblent ; certaines équipes gardent une disposition de départ à elles ; mais il n’y a pas de norme faisant autorité, pas d’échafaudage partagé, et la structure dérive notablement d’une équipe à l’autre.
Niveau 3 (Standardiser) : Une norme de structure documentée et versionnée est imposée à travers l’organisation ; les nouveaux dépôts sont générés à partir de modèles partagés portant une disposition standard, un README, des fichiers de configuration et une intégration continue ; les écarts passent par un processus d’exception documenté plutôt que de se produire silencieusement.
Niveau 4 (Gérer) : La conformité à la norme est mesurée et contrôlée avec des données : des vérifications automatisées rapportent quelle fraction des dépôts correspond à la disposition, à quel point les dépôts modélisés ont dérivé, la complétude des README, et les violations de direction de dépendance, tous suivis par rapport à des références ; les temps d’intégration et de navigation sont mesurés ; les exceptions sont consignées et révisées, et les changements de modèle sont approuvés sur preuve plutôt que sur opinion.
Niveau 5 (Orchestrer) : La structure est continuellement améliorée et adaptative : les améliorations de modèle se propagent automatiquement aux dépôts existants, la gouvernance de structure est intégrée à la sécurité, à la conformité et à l’outillage de plateforme, et la norme évolue délibérément à mesure que les langages, les architectures et le portefeuille changent, gardant l’uniformité élevée pendant que l’organisation change autour d’elle.

Pistes de réflexion

Quels dossiers de premier niveau devraient être vraiment universels à travers votre organisation, et lesquels devraient être optionnels ?
Comment gardez-vous les dépôts générés à partir d’un modèle de dériver de celui-ci avec le temps ?
Où se situe la ligne entre une hiérarchie stratifiée utile et une cérémonie de dossiers sur-ingénierée ?
En quoi votre norme de structure devrait-elle différer, si tant est qu’elle doive différer, entre une approche monorepo et multi-dépôts ?
Quel est le bon processus d’exception pour un projet dont les besoins réels ne correspondent pas à la disposition standard ?
Quelle part de votre structure peut être vérifiée automatiquement, et qu’est-ce qui repose encore sur la relecture humaine ?
Qui est propriétaire de la norme de structure et de ses modèles, et comment les changements sont-ils proposés et déployés ?

Points clés à retenir

Organisez chaque dépôt pour que n’importe quel ingénieur puisse naviguer n’importe quelle base de code par anticipation, en suivant le principe de moindre surprise.
Adoptez une disposition de premier niveau cohérente (source, tests, documentation, construction, déploiement, scripts, exemples, spécification) et faites du README le point d’entrée.
Versionnez la configuration d’éditeur et d’outillage (comme .editorconfig) pour que les conventions soient actives, pas seulement écrites.
Imposez la structure par l’échafaudage et les modèles pour que les nouveaux dépôts soient corrects par défaut.
À l’échelle, la valeur est dans l’uniformité : gouvernez la norme, gérez la dérive, et n’autorisez les écarts que par exception documentée.

Références et lectures complémentaires

Robert C. Martin, Clean Architecture: A Craftsman’s Guide to Software Structure and Design
Steve McConnell, Code Complete: A Practical Handbook of Software Construction
Andrew Hunt et David Thomas, The Pragmatic Programmer
Titus Winters, Tom Manshreck et Hyrum Wright (dir.), Software Engineering at Google
Scott Chacon et Ben Straub, Pro Git
Documentation du projet EditorConfig (comme norme de référence pour la configuration d’éditeur)