Aller au contenu

Nommer les choses

Les principes de nommage, la langue, et un tableau de ce qui s'écrit comment.

Voir en Markdown

Un bon nom évite un commentaire. Cette page donne les principes. Les trois pages suivantes donnent, pour chaque chose qu’on nomme, une règle avec son identifiant, la forme à écrire, et ce qu’il ne faut pas écrire.

  • Nommer en TypeScript : dossiers, fichiers, composants, fonctions, types, constantes, tests.
  • Nommer dans la base : tables, colonnes, clés, index, fonctions SQL, déclencheurs, migrations, droits.
  • Nommer le reste : CSS, scripts, variables d’environnement, branches, commits, modules, plugins, portes.

Premier jet. Les formes relevées viennent d’un relevé du dépôt. Tout ce qui n’est pas marqué « règle écrite » est à valider par le propriétaire avant de devenir une règle. Les cinq principes ci-dessous sont une proposition de rédaction.

Règle écrite Décidée et écrite dans un document du projet. Elle s’applique sans discussion.

Usage constaté Le dépôt la suit presque partout, mais aucun document ne la décide. Suivez-la ; ce n’est pas encore une règle.

À décider Le dépôt hésite entre deux formes. Ne tranchez pas seul : demandez.

1. Un nom dit la chose, en entier. calculer_les_alertes, pas calc_al. Pas d’abréviation, sauf celles du tableau ci-dessous.

2. Un mot, une chose. Si « état » désigne l’état d’une opération, il ne désigne pas aussi l’état d’un formulaire. Avant de créer un nom, cherchez s’il existe déjà : c’est la règle « réutiliser avant d’écrire », appliquée aux noms. Aujourd’hui, trois composants portent le nom Formulaire et trois autres le nom Rattacher : c’est exactement ce qu’il ne faut plus faire.

3. On nomme par le métier, pas par la technique. LigneAFiltrer, pas RowData. Le vocabulaire est celui des gens qui se servent de l’application.

4. Une casse par sorte de chose, jamais deux. Voir le tableau ci-dessous.

5. Un nom ne dit pas l’histoire. Pas de nouveau_, ancien_, v2, temp. Si une chose est remplacée, l’ancienne disparaît.

  • L’interface est en français, écrite pour les gens qui s’en servent.
  • Le code passera en anglais, en une seule fois, par un script qui applique un glossaire français-anglais. Les noms devront dire la chose en anglais courant.
  • D’ici là, le domaine est nommé en français (affaire, operation, poser_un_rappel). Un nom nouveau suit la langue des objets qu’il touche. Jamais à moitié : import_job qui pointe vers affaire est pire que l’une ou l’autre langue.
  • Ne pas traduire les noms des bibliothèques (useState, error, data, router).
  • Pas d’accent dans un identifiant : creer, pas créer.

Toutes les formes ci-dessous valent dans les deux langues. Les exemples sont ceux du dépôt d’aujourd’hui.

Quand un nom tient en plusieurs mots, on les relie toujours de la même façon. Voici les cinq formes utilisées, avec leur nom :

Nom de la forme Comment on l’écrit Exemple
kebab-case minuscules, mots reliés par des tirets preparer-une-tournee
snake_case minuscules, mots reliés par des tirets bas ligne_affaire
camelCase mots collés, majuscule au début de chaque mot sauf le premier nomDeLaSemaine
PascalCase mots collés, majuscule au début de chaque mot TableauFiltrable
SCREAMING_SNAKE_CASE majuscules, mots reliés par des tirets bas CLE_ORDRE_OPERATIONS
Quoi Casse Exemple (aujourd’hui)
Dossier d’écran kebab-case preparer-une-tournee/
Fichier TypeScript kebab-case tableau-filtrable.tsx
Composant React PascalCase TableauFiltrable
Hook use + PascalCase useFenetre
Fonction, variable camelCase nomDeLaSemaine
Type PascalCase EtatIntervention
Constante de configuration SCREAMING_SNAKE_CASE MENU, CLE_ORDRE_OPERATIONS
Table, colonne, fonction SQL snake_case ligne_affaire, cree_le
Migration AAAAMMJJHHMMSS_phrase_snake_case.sql 20261017240000_une_societe_cree_ses_roles.sql
Classe et variable CSS kebab-case .tete-de-fiche, --nav-actif
Script Node ou shell kebab-case verifier-les-routes.mjs
Script Python snake_case corrections_connues.py
Variable d’environnement SCREAMING_SNAKE_CASE préfixe du projet
Code de droit domaine.niveau affaires.voir
Module, rôle minuscules, un mot ou snake_case habilitations, charge_affaires