Standards de code

Ces règles s'appliquent à tout le code livré dans le dépôt. Une partie est vérifiée automatiquement (TypeScript strict, ESLint, solhint, synchronisation de .env.example), le reste relève de la revue. Les conventions d'organisation propres à chaque projet (découpage en modules, nommage des fichiers) sont détaillées dans Conventions de code.

#Règles communes

#Pas de commentaires

Le code ne contient pas de commentaires explicatifs : les noms de variables, de fonctions et les tests portent l'intention. Une fonction qui a besoin d'un commentaire pour être comprise doit être renommée ou découpée. L'explication des choix revient à la documentation et aux ADR.

Trois exceptions sont nécessaires au fonctionnement des outils :

#Pas d'émojis

Ni dans le code, ni dans les messages d'API, ni dans les interfaces, ni dans les commits. Les icônes de l'interface sont des SVG.

#Backend

#Organisation d'un module

Chaque domaine de backend/src/api/ suit le même découpage en cinq fichiers, par exemple pour les partenaires :

Chaque fichier exporte une instance unique (export const partnersService = new PartnersService()) et l'exporte par défaut. Le guide Ajouter un endpoint montre le découpage sur un exemple complet.

#Réponses et erreurs

Un contrôleur entoure toujours l'appel du service d'un try et passe l'erreur à next(error). Le format complet est décrit dans Réponses et erreurs.

#Promesses

Toute promesse est attendue (await) ou explicitement ignorée avec void. ESLint l'impose dans src/ et prisma/ avec @typescript-eslint/no-floating-promises en erreur (backend/eslint.config.mjs) :

void lotteryIndexer.syncOnce();

Une promesse lancée en arrière-plan doit traiter son propre échec, sans quoi une erreur non gérée arrête le processus :

walletService
  .grantWelcomeEthers(user)
  .catch((error: Error) => logger.warn(`Dotation de bienvenue différée : ${error.message}`));

#Configuration

• process.env n'est lu que dans backend/src/config/. Le reste du code importe env depuis env.config.ts, déjà typé et validé.
• Toute nouvelle variable est ajoutée au schéma Zod et à backend/.env.example ; npm run env:check vérifie la synchronisation. La procédure complète est dans Ajouter une variable d'environnement.

#Appels sortants

Chaque appel vers un service extérieur a un délai maximal. C'est le cas aujourd'hui :

Un nouveau client HTTP ou SDK doit recevoir un délai du même ordre.

#Journalisation

Les journaux passent par logger.util.ts (winston), jamais par console.log dans src/. Une adresse email est masquée avec maskEmail avant d'être journalisée ; une clé privée, un jeton ou un code à usage unique ne sont jamais journalisés.

#Migrations

Toute migration Prisma respecte l'ADR 0003 : expand/contract, SET lock_timeout = '5s' en première ligne, contraintes ajoutées en NOT VALID puis validées. Voir Ajouter une migration et Migrations expand et contract.

#Frontend web

Voir Stack et structure et le guide Ajouter une page web.

#Application mobile

Voir le guide Ajouter un écran mobile.

#Smart contracts

Règles volontairement désactivées dans .solhint.json : reason-string (remplacé par les erreurs personnalisées), not-rely-on-time (les tours sont bornés par block.timestamp), avoid-low-level-calls (les versements utilisent call), use-natspec, gas-indexed-events, gas-strict-inequalities et gas-struct-packing.

#Site de l'Office de Tourisme

Voir Architecture JavaScript.

#Documentation

Un changement de comportement documenté met à jour la documentation dans la même pull request. Les règles de rédaction sont dans Écrire la documentation.