Comment les conventions des frameworks réduisent le besoin de documentation

Ce que signifie que les conventions remplacent la documentation

Les conventions d'un framework sont les « manières par défaut de faire les choses » que le framework encourage silencieusement — ou qu'il attend carrément. Plutôt que chaque équipe invente sa propre organisation de dossiers, son propre schéma de nommage ou son flux requête/réponse, le framework fournit un modèle partagé. Si vous le suivez, les autres développeurs peuvent prédire où se trouvent les éléments et comment ils se comportent sans avoir besoin d'une longue explication.

Pourquoi les équipes écrivent de la documentation

La plupart de la documentation n'est pas écrite parce que les gens aiment rédiger des docs. Elle existe pour résoudre quelques problèmes récurrents :

• Onboarding : aider les nouveaux développeurs à comprendre où commencer et comment le projet est organisé
• Cohérence : empêcher chacun de résoudre le même problème de façons différentes
• Archivage des décisions : consigner pourquoi une approche particulière a été choisie (souvent après des arbitrages)

Les conventions s'attaquent particulièrement bien aux deux premiers. Quand « où placer X » et « comment nommer Y » sont déjà décidés par le framework, il y a moins à expliquer et moins à débattre.

Les conventions réduisent la documentation — elles ne l'effacent pas

« Les conventions remplacent la documentation » ne veut pas dire qu'un projet devient sans documentation. Cela signifie qu'une grande part des conseils basiques passe de la prose à une structure prévisible. Plutôt que de lire une page de wiki pour apprendre où vont les contrôleurs, vous l'inférez parce que le framework attend des contrôleurs à un endroit donné (et les outils, générateurs et exemples le renforcent).

Le résultat est moins de documentation sur l'évident, et plus d'efforts pour documenter ce qui est vraiment spécifique au projet : règles métier, choix d'architecture inhabituels et exceptions volontaires.

Ce que vous apprendrez dans cet article

Cet article s'adresse aux développeurs, tech leads et équipes orientées produit qui veulent des bases de code plus claires et un onboarding plus rapide sans maintenir un site de docs tentaculaire.

Vous apprendrez comment les conventions des frameworks créent une « documentation implicite », quels types de choses les conventions standardisent typiquement, où elles cessent d'aider, et ce qui mérite encore une documentation explicite — afin que la clarté augmente même si la quantité de docs diminue.

Pourquoi les conventions fonctionnent : des choix partagés valent mieux que de longues explications

« Convention over configuration » signifie qu'un framework fait des choix sensés pour vous — tant que vous suivez ses règles implicites. Plutôt que d'écrire (et de lire) des pages d'instructions d'installation, les équipes s'appuient sur des valeurs par défaut partagées que tout le monde reconnaît.

Une analogie simple

Pensez-y comme conduire dans un pays où tout le monde accepte de rouler à droite, de s'arrêter au feu rouge et de respecter les panneaux standard.

Vous pourriez écrire un manuel détaillé pour chaque intersection (« Si vous voyez un octogone rouge, arrêtez ; si le feu est vert, avancez… »), mais ce n'est pas nécessaire — la convention est déjà connue et appliquée de façon cohérente.

Les conventions de framework fonctionnent pareil : elles transforment le « comment on fait ici » en comportements prévisibles.

Les valeurs par défaut évitent d'expliquer chaque étape

Quand un framework a des valeurs par défaut, vous n'avez pas à documenter chaque petite décision. Le framework (et votre équipe) peut présumer de patterns comme :

• où vont les fichiers (contrôleurs dans un dossier, templates dans un autre)
• comment les choses sont nommées (un modèle User correspond à des données users)
• comment les fonctionnalités courantes sont câblées (routing, validation, paramètres d'environnement)

Cette base partagée réduit la documentation de « voici chaque étape pour configurer X » à « nous suivons les defaults du framework, sauf indication contraire. » Cela réduit aussi la charge mentale lors de l'onboarding : les nouveaux développeurs devinent plus souvent correctement, parce que le code correspond à ce qu'ils ont vu ailleurs.

Le compromis : moins de flexibilité, plus de cohérence

Les conventions ne sont pas gratuites. L'inconvénient est que vous renoncez parfois à des structures de dossiers atypiques, un nommage personnalisé ou des workflows très sur mesure.

L'avantage est la cohérence : moins de débats, moins de surprises, moins de règles « savoir-faire tribal » que seuls les anciens retiennent. Les équipes avancent plus vite parce qu'elles passent moins de temps à expliquer et plus de temps à construire.

Les conventions fonctionnent mieux quand elles sont largement partagées

Une convention ne fait économiser la documentation que si les gens la connaissent déjà — ou peuvent l'apprendre une fois et la réutiliser partout.

C'est pourquoi les frameworks populaires sont puissants : leurs conventions sont largement enseignées, largement utilisées et répétées à travers de nombreuses bases de code. Quand votre projet reste proche de ces defaults partagés, votre code devient compréhensible par défaut, avec bien moins d'explications écrites nécessaires.

Les 5 choses que les conventions de framework standardisent généralement

Les conventions de framework sont des raccourcis partagés. Elles standardisent les questions que tout nouveau coéquipier se pose le premier jour : « Où cela va-t-il ? » et « Comment l'appeler ? » Quand ces réponses sont prévisibles, vous pouvez remplacer des pages de docs par quelques defaults cohérents.

1) Structure des dossiers et fichiers

La plupart des frameworks poussent une structure de projet reconnaissable : une place pour l'UI, une pour les routes, une pour l'accès aux données, une pour les tests. Cette cohérence compte parce que l'on n'a pas à lire un guide pour trouver « la partie qui rend une page » versus « la partie qui parle à la base ».

Les meilleures conventions font des tâches courantes un automatisme : ajouter un nouvel écran, vous savez déjà dans quel dossier il appartient.

2) Conventions de nommage

Les règles de nommage réduisent le besoin d'explications du type « Nos contrôleurs sont dans X et doivent être branchés dans Y. » Au lieu de cela, les noms impliquent des rôles.

Exemples courants :

• pages/composants nommés d'après ce qu'ils affichent (et avec une casse prévisible)
• tests nommés d'après l'unité qu'ils couvrent
• fichiers nommés pour correspondre aux exports (pour que la recherche fonctionne comme prévu)

3) Routage et URLs

Beaucoup de frameworks font correspondre des fichiers aux routes (ou rendent les routes faciles à déduire). Si vous pouvez deviner l'URL à partir du nom de fichier — ou vice versa — vous n'avez pas besoin d'un manuel de routage pour chaque fonctionnalité.

La convention fixe aussi les attentes autour des routes dynamiques, des routes imbriquées et du traitement des 404, donc « comment ajouter un nouvel endpoint ? » a une réponse standard.

4) Patterns d'accès aux données

Les conventions définissent souvent où se trouve le code « data » : modèles, repositories, services, migrations, fichiers de schéma. Même si votre app est petite, avoir un emplacement convenu pour l'accès aux données évite des appels ad hoc dispersés dans le code UI.

5) Scripts et commandes courants

Des commandes standard (run, test, build, lint, format) enlèvent l'ambiguïté. Un nouveau développeur ne devrait pas avoir besoin d'une page de wiki pour savoir comment démarrer le projet : npm test (ou l'équivalent) doit être le geste évident.

Quand ces cinq domaines sont cohérents, la base de code répond à la plupart des questions « comment fait-on ici ? »

Comment les conventions transforment la base de code en carte

Une page « comment tout fonctionne » essaie de décrire le système en prose. Elle commence souvent utile, puis se périme au fil des déplacements de dossiers, des changements de noms et des nouvelles fonctionnalités. Les conventions inversent l'idée : au lieu de lire une longue explication, vous lisez la structure.

Des emplacements prévisibles rendent l'orientation facile

Quand un framework (et votre équipe) s'accorde sur où vivent les choses, le dépôt devient navigable comme une grille de ville.

Si vous savez que les composants UI vont dans components/, que les vues de pages vont dans pages/, et que les handlers API sont dans api/, vous arrêtez de demander « où est X ? » parce que le premier emplacement deviné est généralement le bon. Même quand ce n'est pas le cas, votre recherche est contrainte : ce n'est pas n'importe où — c'est dans un petit nombre d'endroits attendus.

Les noms comme panneaux indicateurs

Les conventions font aussi que les noms de fichiers et de symboles portent du sens. Un nouveau venu peut inférer le comportement à partir de l'emplacement et du nom :

• un fichier user.controller gère probablement la logique des requêtes
• une classe UserService contient probablement des règles métier
• un dossier migrations/ contient probablement des modifications de base de données ordonnées et à exécution unique

Cette inférence réduit les questions « expliquez-moi l'architecture » en questions plus petites et faciles à documenter (« Ce service a-t-il le droit d'appeler la base directement ? »).

Les templates maintiennent la carte cohérente

La façon la plus rapide de renforcer la carte est le scaffolding. Les templates de démarrage et les générateurs créent de nouvelles fonctionnalités dans la « bonne » forme par défaut — dossiers, noms de fichiers, wiring de boilerplate et souvent des tests.

C'est important parce que les conventions n'aident que si elles sont appliquées de manière cohérente. Un template est une glissière de sécurité : il oriente chaque nouvelle route, composant ou module dans la structure attendue, de sorte que la base de code reste lisible sans ajouter plus de pages de wiki.

Si vous maintenez des scaffolds internes, liez-les depuis une courte page d'onboarding (par exemple /docs/getting-started) et laissez l'arborescence faire le reste.

Exemples concrets de « documentation implicite »

Les conventions des frameworks agissent souvent comme des instructions silencieuses et intégrées. Plutôt que d'écrire une page expliquant « où vont les choses » ou « comment brancher ceci », le framework a déjà pris la décision — et votre équipe apprend à lire la structure.

Ruby on Rails : « Mettez-le ici et ça marche »

Rails est célèbre pour convention over configuration. Un exemple simple : si vous créez un contrôleur nommé OrdersController, Rails suppose qu'il existe un dossier de vues correspondant à app/views/orders/.

Cette convention peut remplacer une bonne partie de la documentation qui expliquerait autrement :

• où doivent vivre les templates HTML
• comment une URL trouve la bonne action de contrôleur
• comment le contrôleur choisit le template correspondant

Résultat : un nouveau coéquipier peut ajouter une page en suivant le schéma de dossiers, sans demander « où va ce fichier ? »

Django : structure prévisible pour le travail courant

Django encourage une structure d'« app » cohérente. Quand quelqu'un voit une app Django, il s'attend à trouver models.py pour les formes de données, views.py pour le traitement des requêtes, et templates/ pour le HTML.

On pourrait écrire un long guide décrivant l'anatomie du projet, mais les defaults de Django l'enseignent déjà. Quand un coéquipier veut modifier l'apparence d'une page, il sait de regarder dans templates/. Quand il doit ajuster les données stockées, il commence par models.py.

Résultat : corrections plus rapides, moins de temps passé à chercher, moins de questions « quel fichier contrôle ceci ? »

Next.js : routage sans manuel de routage

Next.js réduit la documentation en faisant du routage un reflet direct de votre structure de dossiers. Créez un fichier à app/about/page.tsx (ou pages/about.tsx dans les anciens setups), et vous avez automatiquement une page /about.

Cela supprime le besoin de docs expliquant :

• comment enregistrer les routes
• comment nommer les routes de façon cohérente
• comment ajouter une nouvelle page sans casser la navigation

Résultat : l'onboarding est plus simple — les gens découvrent la forme du site en parcourant les répertoires.

Même idée, écosystèmes différents

Rails, Django et Next.js ont des apparences différentes, mais le principe est identique : des valeurs par défaut partagées transforment la structure du projet en instructions. Quand tout le monde fait confiance aux mêmes conventions, la base de code répond à de nombreuses questions « comment on fait ici ? » — sans autre document à maintenir.

Quand les conventions se cassent (et que la confusion revient)

Les conventions de framework paraissent « invisibles » quand elles fonctionnent. Vous pouvez deviner où sont les fichiers, comment ils sont appelés et comment une requête traverse l'application. La confusion réapparaît quand une base de code s'écarte de ces defaults partagés.

Signes que vos conventions s'érodent

Quelques motifs apparaissent tôt :

• trop de dossiers personnalisés qui ne correspondent pas à la structure habituelle du framework (par ex., de nouveaux répertoires top-level créés pour chaque feature sans règles claires)
• nommage incohérent : une partie utilise UserService, une autre UsersManager, une troisième user_service
• patterns ad hoc qui changent d'un écran à l'autre ou d'un endpoint à l'autre (« on l'a géré différemment ici parce que… ») sans guideline stable

Aucun de ces points n'est automatiquement mauvais — mais ils signifient qu'un nouveau venu ne peut plus se fier à la « carte » du framework.

Comment « une exception » devient plusieurs

La plupart des ruptures de conventions commencent par une optimisation locale raisonnable : « Cette feature est spéciale, on la place ici » ou « Ce nom est plus lisible. » Le problème : les exceptions sont contagieuses. Une fois la première exception livrée, le développeur suivant s'en sert comme précédent :

• une deuxième feature copie le dossier personnalisé parce qu'il existe déjà
• une troisième l'adapte légèrement, parce que la deuxième n'était pas tout à fait adaptée
• bientôt vous avez trois façons « acceptables » de faire la même chose

À ce stade, la convention cesse d'être une convention — elle devient du savoir tribal.

Le coût réel : temps, erreurs et réunions

Quand les conventions s'estompent, l'onboarding ralentit parce que les gens ne savent plus où regarder. Les tâches quotidiennes prennent plus de temps (« Lequel de ces dossiers est le bon ? »), et les erreurs augmentent (brancher le mauvais module, utiliser un mauvais pattern, dupliquer la logique). Les équipes compensent en programmant plus de synchronisations, en écrivant des explications de PR plus longues, et en ajoutant des « quick docs » qui se périment.

Une règle simple pour garder la clarté

Personnalisez seulement quand vous avez une raison claire — et laissez une note écrite.

Cette note peut être légère : un court commentaire près de la structure inhabituelle, ou une brève entrée dans une page /docs/decisions expliquant ce qui a changé, pourquoi cela en valait la peine, et quelle approche standard devrait être utilisée à l'avenir.

Ce qu'il faut encore documenter : les exceptions

Les conventions de framework peuvent supprimer des pages d'explications, mais elles n'enlèvent pas la responsabilité. Les parties qu'il faut encore documenter sont celles où votre projet diffère intentionnellement de ce que la plupart des développeurs supposeraient.

Documentez les décisions, pas les basiques

Évitez de réexpliquer le comportement standard du framework. Capturez plutôt les décisions qui affectent le travail au quotidien :

• ce que vous avez choisi (et ce que vous n'avez pas choisi)
• ce qui a changé (et quand)
• pourquoi cela a changé (compromis, contraintes, corrections post-incident)

Exemple : « Nous utilisons des dossiers par feature sous /src/features au lieu de dossiers par couche (/src/components, /src/services) parce que la propriété du code correspond aux équipes et réduit le couplage inter-équipes. » Cette simple phrase évite des semaines de dérive lente.

Laissez de courtes “Notes d'Exception” près du code

Quand une exception est pertinente localement, placez la note localement. Un minuscule README.md dans un dossier, ou un court commentaire en tête de fichier, bat souvent un wiki central que personne ne consulte.

Bonnes cibles :

• un répertoire qui casse la structure habituelle pour une raison
• un module qui doit être initialisé dans un ordre inhabituel
• une règle de nommage qui paraît « fausse » à moins de connaître la contrainte

Gardez ces notes courtes et exploitables : ce qui est différent, pourquoi c'est différent, et quoi faire ensuite.

Créez une petite page “Project Rules”

Ayez une page légère (souvent /docs/project-rules.md ou le README racine) qui liste seulement 5–10 choix clés que les gens risquent de rater :

• conventions de nommage qui diffèrent des defaults du framework
• structure de projet attendue (seulement là où elle diverge)
• votre « golden path » pour ajouter une nouvelle feature ou un endpoint

Ce n'est pas un manuel complet — juste un ensemble partagé de garde-fous.

Quickstart : comment lancer et tester

Même avec des conventions, l'onboarding coince quand on ne sait pas lancer l'app. Ajoutez une courte section « How to run/test » qui correspond aux commandes standard et à votre configuration réelle.

Si la commande conventionnelle est npm test mais que votre projet nécessite npm run test:unit, documentez-le explicitement.

Maintenez la doc à jour via les revues de code

La documentation reste exacte quand elle est traitée comme faisant partie du changement. En revue, demandez : « Est-ce que ceci introduit une nouvelle exception ? » Si oui, exigez la note correspondante (README local, Project Rules ou quickstart) dans la même pull request.

Faire respecter les conventions par l'automatisation plutôt que par plus de docs

Si les conventions sont les « defaults partagés » de votre codebase, l'automatisation est ce qui les rend réelles. Plutôt que d'exiger que chaque développeur se souvienne de règles depuis un wiki, vous rendez les règles exécutables — le projet s'applique alors lui-même.

Vérifications automatisées qui gardent les équipes cohérentes

Une bonne configuration attrape la dérive tôt et discrètement :

• Formatage : auto-format au moment de l'enregistrement et dans la CI (ex. Prettier, gofmt, black) pour éliminer les débats de style.
• Règles de lint : empêcher les erreurs courantes et appliquer les conventions de nommage (ex. règles React hooks, imports inutilisés, « pas d'export par défaut » si c'est votre standard).
• Nommage et structure des tests : imposer des patterns comme *.spec.ts, la structure describe/it ou des assertions requises pour garder la lecture uniforme.
• Frontières de dossiers : bloquer des imports qui violent l'architecture voulue (ex. « features ne peuvent pas importer d'autres features », ou « l'UI ne peut pas importer le code serveur »). Des outils comme des règles ESLint, des restrictions TypeScript ou des scripts personnalisés peuvent faire ça.

Ces checks remplacent des paragraphes « merci de vous souvenir de… » par un résultat simple : le code correspond à la convention, ou il ne correspond pas.

Échouer vite : détecter les problèmes avant la fusion

L'automatisation brille parce qu'elle échoue vite :

• les problèmes sont détectés pendant le dev local ou dans la PR, pas des semaines plus tard
• les reviewers passent moins de temps à faire la police du style et plus de temps sur la logique produit
• les nouvelles recrues apprennent les conventions en voyant des erreurs claires et leurs corrections

Gardez les règles minimales — et alignées sur le framework

Les meilleurs jeux de règles sont petits et ennuyeux. Commencez par les defaults du framework, puis ajoutez seulement ce qui protège la clarté (nommage, structure, frontières). Chaque règle supplémentaire est une chose de plus à comprendre ; traitez-les comme du code : ajoutez-les quand elles résolvent un problème récurrent, et retirez-les quand elles n'aident plus.

Les tests comme documentation vivante (quand ils sont écrits pour des humains)

Quand une base de code suit des conventions, les tests peuvent faire plus que « prouver que ça marche ». Ils peuvent expliquer ce que le système est censé faire, en langage clair, juste à côté de l'implémentation.

Écrire des tests qui se lisent comme une histoire

Une règle utile : un test doit décrire un comportement de bout en bout. Si quelqu'un peut parcourir le nom du test et comprendre la promesse du système, vous avez réduit le besoin d'une documentation séparée.

Les bons tests suivent un rythme simple :

• Arrange : préparer un point de départ réaliste
• Act : effectuer une action
• Assert : vérifier le résultat important

Mieux encore, donnez des noms qui reflètent l'intention utilisateur :

• signing_in_with_valid_credentials_redirects_to_dashboard
• checkout_fails_when_shipping_address_is_missing

Ces noms sont une « documentation » que vous ne pouvez pas oublier de mettre à jour — parce que des tests qui échouent forcent la conversation.

Utiliser des tests d'acceptation pour les parcours utilisateurs

Les tests d'acceptation documentent comment le produit se comporte du point de vue de l'utilisateur.

Exemples de comportements que ces tests décrivent :

• un utilisateur s'inscrit, confirme son email et arrive sur la page de bienvenue
• un admin crée un code promo et il s'applique au checkout

Ces tests répondent à la question « Que se passe-t-il quand je fais X ? », souvent la première interrogation d'un nouveau coéquipier.

Les tests unitaires pour les cas limites et les règles

Les tests unitaires excellent quand il s'agit de documenter des règles « petites mais importantes » :

• comportement d'arrondissement
• règles de validation
• contrôles d'autorisation
• cas limites (zones horaires, limites, états vides)

Ils sont particulièrement précieux quand la règle n'est pas évidente à partir des conventions du framework.

Garder fixtures et données d'exemple petites et signifiantes

Les données d'exemple peuvent être une documentation vivante aussi. Un petit fixture bien nommé (ex. user_with_expired_subscription) enseigne le domaine plus vite qu'un paragraphe dans un wiki.

La clé est la retenue : gardez les fixtures minimales, lisibles et centrées sur une seule idée, afin qu'elles restent des exemples dignes de confiance et non un second système à maintenir.

Templates de démarrage : la façon la plus rapide de répandre les conventions

Les templates de démarrage (et les générateurs qui les sous-tendent) sont le moyen le plus rapide de transformer « comment on fait ici » en quelque chose que les gens suivent réellement. Plutôt que d'espérer que chaque membre retienne les bons dossiers, scripts et outillages, vous encodez ces décisions dans un repo qui démarre correctement.

Templates, générateurs et kits de démarrage : vitesses différentes, même objectif

• **Templates ** vous donnent une base copiable (ex. « nouveau service », « nouvelle app frontend »).
• **Générateurs ** (CLI) peuvent poser quelques questions, puis créer des fichiers cohérents, le nommage et le wiring.
• **Starter kits ** incluent souvent non seulement la structure du code, mais aussi la CI, le linting, les tests et les defaults de déploiement.

Les trois réduisent la « dette documentaire » parce que la convention est encodée dans le point de départ, pas écrite dans un wiki qui dérive.

En pratique, c'est aussi l'endroit où des outils comme Koder.ai peuvent aider : quand vous générez une nouvelle app React, un backend Go, un schéma PostgreSQL ou un client Flutter depuis un workflow piloté par chat, vous pouvez maintenir les équipes sur une « golden path » en faisant que la sortie par défaut respecte vos conventions (puis en exportant le code source dans votre repo).

Standardiser la configuration pour que « chaque repo ne soit pas différent »

La plupart des confusions à l'onboarding ne portent pas sur la logique métier, mais sur où se trouvent les choses et comment les lancer. Un bon template rend les tâches courantes identiques entre les repos : mêmes scripts, mêmes noms de dossiers, mêmes commandes de vérification, mêmes attentes de PR.

Si vous ne faites rien d'autre, alignez-vous sur :

• dossiers prévisibles (ex. /src, /test, /docs pour les exceptions uniquement)
• une unique façon de lancer, tester et lint via des scripts de package
• une pipeline CI par défaut qui exécute ces scripts automatiquement

Une checklist légère « nouveau projet »

Gardez-la assez courte pour que les équipes ne la sautent pas :

1. Structure de dossiers et règles de nommage
2. Setup en une commande (ex. install + dev)
3. Scripts test, lint et format
4. CI qui s'exécute sur chaque PR
5. README basique : but, prérequis, et les 3–5 commandes nécessaires

Ne pas fossiliser : le template peut devenir le problème

Le plus grand risque est de copier un vieux template « parce que ça marchait l'année dernière ». Dépendances obsolètes, scripts hérités ou patterns abandonnés se propagent rapidement lorsqu'ils figurent dans un starter.

Traitez les templates comme des produits : versionnez-les, révisez-les régulièrement, et mettez-les à jour quand vos conventions changent. (Si votre plateforme supporte snapshots et rollback — Koder.ai le fait — utilisez cela pour itérer en toute sécurité sur les starters sans casser la baseline de tout le monde.)

Une checklist pratique pour réduire les docs sans perdre en clarté

Réduire la documentation ne veut pas dire laisser les gens deviner. Cela signifie rendre le "chemin heureux" si cohérent que la plupart des questions se résolvent d'elles-mêmes, et n'écrire que ce qui est vraiment inhabituel.

1) Faites un rapide auto-audit (trouvez les vraies frictions)

Cherchez les endroits où les gens posent sans cesse les mêmes questions sur Slack, dans les commentaires de PR, en standup ou lors de l'onboarding. Quelques prompts :

• « Où doit vivre ce fichier ? »
• « Comment nomme-t-on ceci ? »
• « Comment ajouter une nouvelle page/job/endpoint ? »
• « Pourquoi ça marche différemment dans ce module ? »

Si vous entendez la même question deux fois, vous n'avez probablement pas besoin de plus de prose — vous avez besoin d'une convention.

2) Choisissez : adoptez le default du framework, ou documentez une déviation délibérée

Pour chaque question récurrente, décidez :

• On lutte contre le framework : revenez aux defaults du framework (routage, layout des dossiers, nommage, gestion des erreurs). Les defaults sont déjà « documentés » par l'écosystème.
• On a une bonne raison de déroger : conservez la déviation, mais rendez-la explicite et facile à repérer.

Règle utile : si la déviation n'économise pas du temps réel ou ne prévient pas un risque réel, elle n'en vaut probablement pas la peine.

3) Créez une petite page « Conventions & Exceptions »

Gardez une seule page courte (ex. /docs/conventions) qui liste :

• les 5–10 conventions que tout le monde doit supposer
• le petit ensemble d'exceptions (avec la raison et un exemple)

Limitez-vous à ce que quelqu'un a besoin dans sa première semaine. Si cela commence à gonfler, c'est souvent le signe qu'il faut plutôt simplifier la base de code.

4) Mettez en place un rythme : revisitez les conventions trimestriellement

Les apps évoluent. Planifiez une revue légère tous les trimestres :

• quels nouveaux patterns sont apparus ?
• quelles exceptions sont devenues "normales" (et doivent devenir des conventions) ?
• quelles conventions sont ignorées (et pourquoi) ?

Conclusion

Privilégiez les defaults du framework autant que possible, et ne documentez que ce qui diffère — clairement, brièvement et à un seul endroit.