Les conventions d'un framework rendent les applications plus faciles à comprendre sans longs docs. Découvrez ce que couvrent les conventions, où elles échouent et comment documenter uniquement les exceptions.
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.
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 :
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 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.
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.
« 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.
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.
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 :
User correspond à des données users)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.
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.
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 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.
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.
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 :
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.
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.
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 ? »
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.
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 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 :
user.controller gère probablement la logique des requêtesUserService contient probablement des règles métiermigrations/ contient probablement des modifications de base de données ordonnées et à exécution uniqueCette 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 ? »).
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.
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.
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 :
Résultat : un nouveau coéquipier peut ajouter une page en suivant le schéma de dossiers, sans demander « où va ce fichier ? »
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 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 :
Résultat : l'onboarding est plus simple — les gens découvrent la forme du site en parcourant les répertoires.
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.
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.
Quelques motifs apparaissent tôt :
UserService, une autre UsersManager, une troisième user_serviceAucun de ces points n'est automatiquement mauvais — mais ils signifient qu'un nouveau venu ne peut plus se fier à la « carte » du framework.
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 :
À ce stade, la convention cesse d'être une convention — elle devient du savoir tribal.
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.
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.
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.
Évitez de réexpliquer le comportement standard du framework. Capturez plutôt les décisions qui affectent le travail au quotidien :
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.
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 :
Gardez ces notes courtes et exploitables : ce qui est différent, pourquoi c'est différent, et quoi faire ensuite.
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 :
Ce n'est pas un manuel complet — juste un ensemble partagé de garde-fous.
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.
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.
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.
Une bonne configuration attrape la dérive tôt et discrètement :
*.spec.ts, la structure describe/it ou des assertions requises pour garder la lecture uniforme.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.
L'automatisation brille parce qu'elle échoue vite :
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.
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.
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 :
Mieux encore, donnez des noms qui reflètent l'intention utilisateur :
signing_in_with_valid_credentials_redirects_to_dashboardcheckout_fails_when_shipping_address_is_missingCes noms sont une « documentation » que vous ne pouvez pas oublier de mettre à jour — parce que des tests qui échouent forcent la conversation.
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 :
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 excellent quand il s'agit de documenter des règles « petites mais importantes » :
Ils sont particulièrement précieux quand la règle n'est pas évidente à partir des conventions du framework.
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.
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.
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).
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 :
/src, /test, /docs pour les exceptions uniquement)Gardez-la assez courte pour que les équipes ne la sautent pas :
install + dev)test, lint et formatLe 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.)
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.
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 :
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.
Pour chaque question récurrente, décidez :
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.
Gardez une seule page courte (ex. /docs/conventions) qui liste :
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.
Les apps évoluent. Planifiez une revue légère tous les trimestres :
Privilégiez les defaults du framework autant que possible, et ne documentez que ce qui diffère — clairement, brièvement et à un seul endroit.
Les conventions d'un framework sont les modèles par défaut que le framework attend que vous suiviez : structure des dossiers, nommage, routage, accès aux données et commandes courantes. Si vous vous y tenez, d'autres développeurs peuvent déduire où se trouvent les éléments et comment ils fonctionnent sans lire une documentation spécifique au projet.
Parce qu'il est difficile de garder la prose exacte à jour quand le code change. La documentation existe principalement pour :
Les conventions couvrent bien les deux premiers points en rendant la structure prévisible.
Non. Les conventions réduisent la documentation sur l'évident (où placer les fichiers, comment les routes sont reliées), mais il faut toujours documenter ce qui est spécifique au projet : règles métier, déviations intentionnelles et décisions clés. Pensez « moins de documentation, mais de meilleure qualité ».
Elles standardisent les questions récurrentes du « premier jour » :
Quand le code suit un schéma connu, l'arborescence et les noms de fichiers servent de panneaux indicateurs. Un nouveau venu peut se guider par attente (par ex. « les templates sont dans templates/ », « les migrations sont dans migrations/ ») plutôt que de lire une longue page d'architecture souvent obsolète.
Elles codent les conventions dans des choix par défaut, de sorte que les gens n'ont pas à se fier à leur mémoire. De bons outils de scaffolding génèrent :
Cela empêche la dérive et maintient la « carte » cohérente d'une fonctionnalité à l'autre.
Vous le verrez quand les développeurs ne peuvent plus deviner où mettre quelque chose ou comment l'appeler. Signes courants :
UserService vs UsersManager vs user_service)Quand c'est le cas, l'équipe compense par des explications Slack, des PR plus longues et des « quick docs » qui périment.
Personnalisez seulement s'il y a un bénéfice clair, puis laissez une note légère expliquant la déviation :
README.md dans le dossier inhabituel/docs/decisions ou équivalentCapturez ce qui a changé, pourquoi, et quelle est l'approche standard pour la suite.
Commencez par une base pratique et courte :
Restez concis et exigez la mise à jour de la doc en revue de code si une PR introduit une nouvelle exception.
Utilisez l'automatisation pour rendre les conventions exécutables :
Quand les vérifications échouent en dev local ou en PR, les développeurs apprennent les règles sur le vif, et les réviseurs passent moins de temps à contrôler le style.
Quand ces éléments sont prévisibles, le dépôt devient quasi auto-explicatif.