20 - Conventions d'équipe et ADR

Ce que tu vas apprendre

• Pourquoi les conventions comptent (onboarding, coherence, vitesse)
• Ce qu'il faut standardiser et ce qu'il ne faut pas
• Le format ADR (Architecture Décision Records) avec des exemples
• Comment rédiger un CONTRIBUTING.md utile
• Comment introduire des conventions dans une équipe existante sans braquer les gens

Prerequisites

Article précédent : 19 - Linting

Il y a deux ans, j'ai rejoint un projet ou chaque dev avait son propre style. Un fichier en camelCase, le suivant en kebab-case. Certains services retournaient des exceptions, d'autres des objets Result. Les imports utilisaient des chemins relatifs dans la moitie du code et des alias dans l'autre. Chaque pull request etait une surprise.

Le problème n'etait pas la competence des devs. Le problème etait l'absence de conventions partagees. Chacun faisait au mieux selon ses habitudes. Le résultat : un code qui ressemblait a un patchwork.

Pourquoi les conventions comptent

Les conventions ont trois fonctions. La première est l'onboarding. Un nouveau dev qui arrive sur un projet avec des conventions claires sait immédiatement ou mettre son code, comment nommer ses fichiers, quel pattern de gestion d'erreur utiliser. Sans conventions, il passe deux semaines a observer le code existant et imite le style du fichier le plus proche — qui n'est pas forcement le bon.

La deuxieme est la coherence. Quand tout le code suit les memes patterns, la charge cognitive baisse. Tu ne te demandes plus "comment cette équipe gere les erreurs ici ?" a chaque fichier. C'est pareil partout.

La troisieme est la vitesse. Les conventions eliminent les discussions repetitives en code review. "Pourquoi tu as utilise un enum au lieu d'un union type ?" n'est plus une question si la convention est documentee. L'équipe avance plus vite sur les vrais sujets.

Ce qu'il faut standardiser

Pas tout. Standardiser chaque micro-décision paralyse l'équipe. Concentre-toi sur ce qui provoque des frictions :

Nommage de fichiers et dossiers : une seule convention pour tout le projet. camelCase.ts ou kebab-case.ts, pas les deux. On en parlait dans l'article sur la structure de projet.

Gestion des erreurs : exceptions ou objets Result ? Codes d'erreur ou messages ? Choisis un pattern et applique-le partout. L'article 06 - Gestion des erreurs couvre les options en détail.

Git workflow : branches par feature, nommage des branches (feat/xxx, fix/xxx), messages de commit (conventionnel ou libre), stratégie de merge (squash, rebase, merge).

# Convention de commit : Conventional Commits
feat: add user registration endpoint
fix: prevent duplicate email on signup
refactor: extract validation logic from controller
docs: update API documentation for auth routes
chore: upgrade typescript to 5.4

Structure des imports :

typescript// Convention : ordre des imports
// 1. Librairies externes
import express from "express";
import { z } from "zod";

// 2. Modules internes (shared)
import { logger } from "@/shared/logger";
import { config } from "@/shared/config";

// 3. Modules de la feature
import { UserService } from "./userService";
import { UserSchema } from "./userTypes";

Patterns d'API : format de réponse, pagination, gestion des erreurs HTTP, versionning.

Ce qu'il ne faut pas standardiser

Les préférences individuelles qui n'affectent pas le code : theme de l'éditeur, extensions personnelles, raccourcis clavier. La facon dont un dev organise ses branches locales. Le choix entre for...of et .forEach() quand les deux sont équivalents.

Si une préférence n'a aucun impact sur la lisibilité ou la maintenabilité du code partage, laisse les gens tranquilles.

ADR : Architecture Décision Records

Les ADR documentent les décisions d'architecture importantes. Pas toutes les décisions. Les décisions qui ont un impact durable et qu'un futur dev (ou toi dans 6 mois) pourrait remettre en question.

Le format standard est simple :

markdown# ADR-001 : Utiliser Zod pour la validation des donnees

## Statut
Accepte - 2026-01-15

## Contexte
L'application recoit des donnees de sources multiples (API clients, webhooks,
fichiers CSV). La validation est faite manuellement avec des conditions if/else
eparpillees dans le code. Les erreurs de validation ne sont pas coherentes.

## Decision
Nous utilisons Zod comme librairie de validation pour toutes les entrees de
donnees. Chaque endpoint definit un schema Zod pour ses parametres. Les
erreurs de validation sont formatees automatiquement.

## Consequences
- Positif : validation coherente, types TypeScript generes automatiquement
- Positif : messages d'erreur standardises pour les clients
- Negatif : dependance supplementaire (19 Ko gzippe)
- Negatif : courbe d'apprentissage pour les devs qui ne connaissent pas Zod

Les ADR vivent dans le repository, dans un dossier docs/adr/. Ils sont versiones avec le code. Ils ne sont jamais supprimes : quand une décision est remplacee, on la marque comme "Remplacee par ADR-XXX".

La force des ADR est dans la section "Contexte". Elle explique pourquoi cette décision a ete prise a ce moment-la, avec ces contraintes-la. Six mois plus tard, quand quelqu'un demande "pourquoi on utilise Zod et pas Joi ?", la réponse est dans l'ADR. Plus besoin de fouiller Slack ou de demander au dev qui a fait le choix (et qui a peut-etre quitte l'équipe).

CONTRIBUTING.md : le guide d'entree

Un bon CONTRIBUTING.md répond aux questions qu'un nouveau dev pose le premier jour :

markdown# Contribuer au projet

## Setup
1. Clone le repo
2. `pnpm install`
3. `cp .env.example .env` et remplis les valeurs
4. `pnpm dev` pour lancer en local

## Structure du projet
Voir docs/architecture.md

## Conventions
- Fichiers : kebab-case (user-service.ts)
- Commits : Conventional Commits (feat:, fix:, refactor:)
- Branches : feat/xxx, fix/xxx, chore/xxx
- Tests : coloques avec le code (user.test.ts a cote de user.ts)

## Avant de soumettre une PR
- [ ] Les tests passent (`pnpm test`)
- [ ] Le linting passe (`pnpm lint`)
- [ ] La PR fait moins de 400 lignes modifiees
- [ ] La description de la PR explique le "pourquoi"

Garde-le court. Un CONTRIBUTING.md de 10 pages, personne ne le lit. Mets les détails dans des documents separees et lie-les. Tu peux trouver des exemples de documentation de projets sur paltemps.fr.

Introduire des conventions sans braquer l'équipe

C'est le point delicat. Tu arrives dans une équipe sans conventions et tu veux en mettre en place. Si tu debarques avec un document de 50 pages de regles, tu vas te faire detester. J'ai vu ca arriver.

La méthode qui marche :

Commence par l'automatique. Installe un formatter (Prettier ou Biome) et un linter. Ca standardise 80% du style sans discussion humaine. Personne ne debat avec un outil.

Propose une convention a la fois. Pas dix. Une. "Et si on adoptait Conventional Commits ?" Laisse l'équipe en discuter. Si ca passe, documente-la. Attends quelques semaines avant de proposer la suivante.

Montre, ne dicte pas. Au lieu de dire "il faut faire comme ca", ecris ton code avec la convention proposee. En code review, suggéré doucement : "qu'est-ce que tu penses d'utiliser ce pattern ici ?". Quand les gens voient le benefice, ils adoptent d'eux-memes.

Accepte les compromis. Ta convention préférée n'est pas forcement la meilleure pour cette équipe. Si l'équipe préféré des messages de commit libres plutot que Conventional Commits, c'est ok. L'important c'est qu'ils soient coherents, pas qu'ils suivent ta préférence.

Documente au fur et a mesure. Chaque convention adoptee va dans le CONTRIBUTING.md. Chaque décision d'architecture va dans un ADR. Le document grossit naturellement, sans effort massif.

Le coding standards document

Pour les équipes plus grandes (10+ devs), un document de coding standards centralise est utile. Il regroupe toutes les conventions en un seul endroit :

markdown# Coding Standards

## TypeScript
- Strict mode active
- Pas de `any` explicite (utiliser `unknown` puis type guard)
- Preference pour les types union sur les enums

## API
- RESTful avec JSON
- Reponses : { data, error, meta }
- Codes HTTP standards (201 pour creation, 204 pour suppression)
- Pagination : cursor-based

## Base de donnees
- Noms de tables au pluriel, snake_case
- Migrations nommees : YYYYMMDD_description
- Pas de cascade delete en production

## Tests
- Tests coloques avec le code
- Nommage : describe("NomDuModule") > it("fait quelque chose")
- Pas de test sur les details d'implementation

Ce document est une référencé, pas un cours. Il dit quoi faire, pas pourquoi. Les ADR expliquent le pourquoi quand c'est nécessaire.

Résumé

• Les conventions accelerent l'onboarding, assurent la coherence et eliminent les debats repetitifs
• Standardise ce qui cause des frictions : nommage, erreurs, git workflow, imports
• Les ADR documentent les décisions d'architecture avec leur contexte
• Un CONTRIBUTING.md court et pratique vaut mieux qu'un document exhaustif que personne ne lit
• Introduis les conventions progressivement : automatise d'abord, propose ensuite, documente au fil du temps
• Accepte les compromis : la coherence importe plus que la perfection

Article précédent : 19 - Linting

Article suivant : 21 - Dette technique

Sources

• Michael Nygard, "Documenting Architecture Décisions" - https://cognitect.com/blog/2011/11/15/documenting-architecture-décisions
• Conventional Commits spécification - https://www.conventionalcommits.org/
• GitHub, "Setting guidelines for repository contributors" - https://docs.github.com/en/communities/setting-up-your-project-for-healthy-contributions/setting-guidelines-for-repository-contributors