Conventions

Cette section est prescriptive. Pas "voici quelques idées", voici les règles. Toute PR qui les enfreint sans justification écrite est rejetée.

Pourquoi des règles strictes

Reciprok est un projet long-terme avec une équipe qui va grandir. Chaque "petit raccourci" devient une dette si il n'est pas immédiatement encadré. Les conventions ici servent à :

1. Éviter les débats stériles sur le nommage ou la structure
2. Garder le code lisible par n'importe qui après 6 mois sans y toucher
3. Faciliter le refactor : les fichiers ont une taille bornée, donc on n'a jamais à lire 2000 lignes pour comprendre une fonction
4. Aider l'IA : Claude Code est plus précis quand l'arborescence et les noms sont prévisibles

Pages

Principes directeurs

Tout part de 6 principes non-négociables :

1. Lisibilité > cleverness

Si un junior ne comprend pas le code en première lecture, on réécrit. Pas d'astuces TS ésotériques, pas de chaînes de génériques imbittables. La performance ne justifie jamais la perte de lisibilité (à moins d'être prouvée par benchmark sur le chemin critique).

2. Modules à frontière claire

Chaque module a une responsabilité unique. Les frontières sont matérialisées par les imports : un module ne peut pas importer un fichier "interne" (*.internal.ts) d'un autre module. La porte d'entrée de chaque module est son index.ts.

3. Petits fichiers

Un fichier > 300 lignes est un signal d'alarme. Au-delà de 500 lignes, c'est un refus de PR systématique sauf justification écrite. Détail : voir Seuils de fichiers.

4. kebab-case partout

Tous les fichiers et dossiers en kebab-case. Sans exception (ou alors documentée). Détail : voir Nommage.

5. La dette technique se paie tout de suite

Un TODO sans ticket associé est un TODO qui ne sera jamais fait. Une duplication temporaire devient permanente. Si on identifie une dette pendant une PR, soit on la corrige dans la PR, soit on ouvre un ticket immédiatement avec la PR comme contexte.

6. Tout est testé

Toute fonction de logique métier, toute transition d'état, toute règle de calcul, toute route critique a un test. Pas de PR sans tests sur les zones concernées. Détail : voir Tests.

Exceptions

Une convention peut être enfreinte si et seulement si :

1. Un commentaire // CONVENTION-EXCEPTION: au-dessus du code
2. La raison est expliquée
3. Un lien vers le ticket ou la discussion qui a validé l'exception

Exemple :

// CONVENTION-EXCEPTION: file-thresholds
// Cette factory génère 17 variants Drizzle. Splitter casserait
// l'inférence de types. Discussion: PR #142
export const buildSchemas = () => { /* 320 lignes */ };

Sans ce commentaire, la PR est rejetée.