Normes de codage

Les normes de codage sont des ententes d'équipe sur la façon dont le code devrait être écrit :

• Conventions de nommage (camelCase vs snake_case)
• Formatage (tabulations vs espaces, placement des accolades)
• Organisation du code (structure des fichiers, limites des modules)
• Patrons (comment gérer les erreurs, comment structurer les tests)

Les normes permettent la propriété collective. Quand le code se ressemble partout, n'importe qui peut lire n'importe quel code. Il n'y a pas de « traduction » entre le style de Bob et celui d'Alice.

Les normes réduisent aussi les frictions lors de la révision de code. Au lieu de débattre du formatage, vous discutez de la logique et de la conception. Les débats futiles disparaissent.

Sans normes : Chaque fichier semble différent. Se déplacer entre les modules nécessite un changement de contexte mental. La révision de code devient une guerre de styles.

Avec des normes : La base de code semble unifiée. Lire du code inconnu est plus facile. Les révisions se concentrent sur ce qui compte.

Toutes les conventions ne sont pas égales. Distinguez entre :

Normes sémantiques : Affectent le comportement du code ou sa maintenabilité

• Patrons de gestion des erreurs
• Conventions de journalisation
• Structure des tests
• Patrons de conception d'API

Normes stylistiques : Affectent seulement l'apparence

• Formatage (indentation, longueur de ligne)
• Nommage (camelCase vs snake_case)
• Placement des accolades

Les normes sémantiques méritent discussion. La façon dont l'équipe gère les erreurs est une décision significative avec de vraies conséquences.

Les normes stylistiques devraient être automatisées. Utilisez Prettier, Black, gofmt — des outils qui formatent le code automatiquement. Ne gaspillez pas de temps humain sur tabulations vs espaces.

L'objectif est de retirer les frictions, pas d'atteindre un idéal platonicien du style de code.

L'outillage moderne peut appliquer la plupart des normes automatiquement :

Formateurs : Prettier (JavaScript), Black (Python), gofmt (Go), rustfmt (Rust)

• S'exécutent à la sauvegarde ou comme crochet de pré-commit
• Éliminent complètement les discussions de formatage

Analyseurs : ESLint, Pylint, Clippy, RuboCop

• Détectent les violations de style et les bogues potentiels
• Configurables selon les préférences de l'équipe
• S'exécutent en CI pour empêcher le code non conforme de fusionner

Vérificateurs de types : TypeScript, mypy, Flow

• Appliquent la cohérence des types
• Détectent les erreurs avant l'exécution

Crochets de pré-commit : Husky, pre-commit

• Exécutent des vérifications avant que le code soit commis
• Détectent les problèmes avant qu'ils n'entrent dans le dépôt

Configurez une fois, appliquez pour toujours. Ne comptez pas sur la discipline humaine — automatisez-la.

Les normes peuvent déclencher des opinions fortes. Évitez les débats sans fin :

Commencez avec les conventions existantes. Si le langage ou le framework a un style standard (Go, Rust), utilisez-le simplement. Ne réinventez pas.

Utilisez les valeurs par défaut de l'industrie. Les configurations populaires d'analyseurs/formateurs (Airbnb ESLint, guide de style Google) ont fait leurs preuves.

Décidez rapidement, ajustez plus tard. Choisissez quelque chose de raisonnable. Si ça s'avère problématique, changez-le. Ne bloquez pas le progrès en attendant la norme parfaite.

Rendez-le démocratique mais décisif. Laissez l'équipe voter sur les questions litigieuses. La majorité l'emporte. La minorité accepte la décision.

Rappelez-vous l'objectif. Les normes existent pour réduire les frictions, pas pour exprimer des préférences. Si une discussion prend trop de temps, n'importe quel choix raisonnable convient.

Les normes devraient être documentées — mais gardez-les vivantes :

Quoi documenter :

• Normes sémantiques (comment gérer les erreurs, patrons de tests)
• Justification des choix non évidents (pourquoi nous avons choisi X plutôt que Y)
• Exceptions et quand enfreindre les règles
• Comment proposer des changements

Où documenter :

• Fichier README ou CONTRIBUTING dans le dépôt
• Wiki ou espace de documentation d'équipe
• Commentaires dans la configuration de l'analyseur/formateur

Gardez-la à jour. Une documentation désuète est pire que pas de documentation. Quand vous changez une norme, mettez à jour la documentation.

Rendez-la trouvable. Les nouveaux membres de l'équipe devraient trouver les normes facilement. Ne les enterrez pas dans un labyrinthe de wiki.

La meilleure documentation est le code lui-même. Si vos normes sont appliquées automatiquement, le code démontre ce qui est acceptable.