Nommer pour être relu : conventions de nommage

Un relecteur lit les noms avant de lire la logique : si d, tmp ou traiter2 ne lui disent rien, il doit deviner, puis poser la question à l'auteur, et la revue ralentit. Nommer pour être relu, c'est choisir des noms qui disent ce qu'est la chose ou ce que fait le code, dans une forme que toute l'équipe reconnaît. Cette leçon s'adresse à un Ops qui commence à écrire ou à relire du Python. Elle donne les formes imposées par PEP 8, la méthode pour choisir un bon nom, les règles pour les fichiers et les branches Git, et le contrôle automatique que fait Ruff.

Ce que vous allez apprendre

• Expliquer pourquoi un nom clair accélère la revue de code.
• Choisir la forme d'un nom (variable, constante, fonction, classe, fichier) selon les règles de PEP 8.
• Remplacer un nom cryptique par un nom qui dit le contenu, l'unité ou l'action.
• Nommer un fichier et une branche Git de façon prévisible.
• Faire contrôler la forme des noms par Ruff, et réserver à la revue leur sens.
• Retrouver le même principe pour les ressources cloud et les bases de données.

Prérequis

• Savoir lire un petit script Python, comme dans Lire du code Python hérité (variables, fonctions, import).
• Connaître le principe d'une pull request, la demande de fusion relue avant d'être acceptée, présentée dans Pull requests et code review.

Pourquoi les noms décident-ils de la qualité d'une revue ?

Un nom est la première documentation d'un code, et la seule que le relecteur est sûr d'avoir sous les yeux. Un commentaire peut être périmé, un nom est lu à chaque ligne. Un nom précis évite la question « que contient d ? », un nom trompeur est pire qu'un nom vague : le relecteur croit comprendre, et laisse passer une erreur. Comparez deux versions d'une même fonction, qui calcule le nombre de jours avant l'expiration d'un certificat :

from datetime import date

def f(d):
    n = (d - date.today()).days
    return n

from datetime import date

def jours_avant_expiration(date_expiration):
    jours_restants = (date_expiration - date.today()).days
    return jours_restants

La logique est identique. Seule la seconde se relit sans explication orale : on sait ce qu'on lui passe, ce qu'elle rend, et dans quelle unité. Cette économie compte dès que le script est repris par un collègue, ou par vous-même six mois plus tard. Les Ops connaissent déjà cette loi côté infrastructure : un serveur nommé d'après une ville ne dit pas s'il est en production, et la confusion coûte cher. Le code obéit à la même règle.

Quelle forme de nom pour quel élément en Python ?

PEP 8, le guide de style officiel de Python, fixe la forme du nom selon ce qu'il désigne. Un PEP (Python Enhancement Proposal) est un document qui décrit une convention ou une évolution du langage ; le numéro 8 porte sur le style du code. Suivre sa convention, c'est écrire comme le reste de l'écosystème, donc être lu sans friction.

Ce que le nom désigne	Forme	Exemple
Variable, paramètre	snake_case : minuscules, mots séparés par _	jours_restants
Fonction	snake_case (le verbe en tête est une habitude, pas une règle PEP 8)	charger_inventaire
Constante	MAJUSCULES_AVEC_TIRETS_BAS	SEUIL_ALERTE_JOURS
Classe	PascalCase : majuscule à chaque mot, sans _	VerificateurCertificat
Module (fichier .py)	minuscules, _ si besoin	certificats.py
Usage interne	préfixe _	_lire_fichier

Glissez pour voir

Une constante est une valeur définie une fois en haut du fichier et jamais modifiée ensuite : Python ne l'interdit pas, c'est la forme en majuscules qui le dit au lecteur. Un nom préfixé par _ annonce, par convention, qu'il ne fait pas partie de ce que l'outil expose aux autres.

D'autres langages font autrement : camelCase (maVariable) en JavaScript ou en Java pour les variables, kebab-case (ma-page) pour les adresses web. La règle utile n'est pas d'apprendre toutes les formes, c'est de suivre celle du langage et du projet où l'on écrit. Un script Python en camelCase se lit comme une faute de frappe.

Comment choisir un nom qui dit ce que le code fait ?

Un bon nom dit le contenu d'une donnée, ou l'action d'une fonction, sans que le lecteur ait à ouvrir le code. Quatre habitudes suffisent pour un débutant : nommer le contenu plutôt que le type, ajouter l'unité quand il y en a une, démarrer une fonction par un verbe, et réserver les noms d'une lettre à de très petites boucles.

Plutôt que	Écrire	Pourquoi
a = 10	nombre_utilisateurs = 10	le nom dit ce qu'on compte
delai = 30	delai_secondes = 30	l'unité évite une erreur d'un facteur 60
temp	temperature_celsius	un nom générique ne dit rien
ok	certificat_valide	un booléen (vrai ou faux) se lit comme une question
process()	envoyer_alerte()	la fonction commence par un verbe
Data1	Client	une classe désigne une chose, au singulier

Glissez pour voir

Évitez les noms génériques (data, tmp, final, test2), les abréviations que seul l'auteur comprend (chk, usr), et les lettres l, O et I seules, que l'on confond avec 1 et 0. À l'inverse, un nom n'a pas à raconter une phrase : liste_des_noms_de_machines_a_verifier n'est pas plus clair que machines_a_verifier. Visez le nom le plus court qui reste univoque dans son contexte.

Pour les fonctions, un test simple : si vous devez écrire « et » dans le nom (lire_et_envoyer), la fonction fait deux choses, et deux noms vaudraient mieux. C'est un indice, pas une règle absolue, mais il signale souvent un découpage à revoir.

Comment nommer les fichiers et les branches Git ?

Un fichier ou une branche se nomme pour qu'on le retrouve et qu'on devine son contenu, en minuscules et sans espaces. Pour un fichier Python, utilisez des minuscules et _ (certificats.py, lecture_inventaire.py), sans espaces ni accents, qui compliquent les commandes et les scripts. Un fichier de tests commence par test_ (test_certificats.py) : c'est l'un des deux motifs que pytest découvre par défaut (l'autre est *_test.py), et la convention retenue par Tester une automatisation.

Une branche Git est une ligne de travail parallèle dans le dépôt. La convention courante donne un préfixe, un /, puis une description courte en minuscules séparée par des tirets :

Préfixe	Usage	Exemple
feature/	nouvelle fonctionnalité	feature/export-json
fix/	correction d'un défaut	fix/lecture-certificat-vide
chore/	tâche technique (dépendances, CI)	chore/maj-pyyaml
release/	préparation d'une version	release/2.1.0

Glissez pour voir

Évitez les noms sans contexte (temp, test, branche1, wip) : personne ne sait dans deux semaines ce qu'elles contiennent. Ne donnez jamais à une branche le nom exact d'un tag : si v2.1.0 désigne à la fois une branche et un tag, Git ne sait plus ce que vous voulez dire quand vous tapez ce nom. Avec le préfixe, release/2.1.0 reste distinct du tag v2.1.0. Le guide Gestion des branches Git détaille les préfixes, le nettoyage des branches terminées et la référence au ticket.

Deux autres noms suivent le même esprit. Les jobs de CI (les tâches que le robot d'intégration continue exécute) se nomment comme les fonctions : un verbe et son objet, en minuscules séparées par des tirets (run-tests, deploy-backend), pour que la liste des jobs se lise comme un plan d'action. Les messages de commit suivent leur propre convention, présentée dans Conventional Commits.

Comment faire contrôler les noms par Ruff ?

Ruff vérifie la forme des noms avec ses règles N, issues de pep8-naming. Il ne les active pas par défaut : on les ajoute à la configuration du projet, dans pyproject.toml. Ruff est un linter : un outil qui lit le code sans l'exécuter et signale les écarts à des règles. La leçon Relire une pull request s'en sert pour le contrôle mécanique d'une revue, et la liste des familles de règles est dans Ruff, le linter et formateur Python.

Pour essayer, créez un projet d'essai, installez Ruff comme outil de développement (la leçon sur la relecture le présente plus en détail ; sans uv, pip install ruff fait la même chose), puis ajoutez à pyproject.toml la section ci-dessous :

mkdir essai-nommage && cd essai-nommage
uv init --vcs none   # --vcs none : pas de dépôt Git pour un simple essai
uv add --dev ruff

[tool.ruff.lint]
extend-select = ["N"]

La clé extend-select ajoute les règles N aux règles par défaut de Ruff. N'utilisez pas select, qui les remplace : il faudrait alors lister aussi les règles E et F, et E501 (ligne trop longue) ferait remonter des diagnostics sans rapport avec les noms. Créez à la racine du projet d'essai un fichier fautif.py volontairement fautif : une classe en snake_case, une fonction et un paramètre en PascalCase, une variable en PascalCase.

class verificateur_certificat:
    pass


def VerifierExpiration(NomHote):
    JoursRestants = 30
    return JoursRestants

Lancé depuis le dossier du projet, uv run ruff check . répond, avec une sortie observée avec Ruff 0.17.1 en octobre 2026, donnée à titre illustratif (le texte des messages évolue d'une version de Ruff à l'autre). Pour la lisibilité, seule la première ligne de chaque diagnostic est reproduite :

N801 Class name `verificateur_certificat` should use CapWords convention
N802 Function name `VerifierExpiration` should be lowercase
N803 Argument name `NomHote` should be lowercase
N806 Variable `JoursRestants` in function should be lowercase
Found 4 errors.

Chaque diagnostic donne la règle (N801), le nom fautif et la convention attendue (CapWords, minuscules) ; Ruff ajoute dessous le fichier, la ligne et le passage souligné, puis conclut par Found 4 errors. et un code de sortie 1. Aucun E501 n'apparaît. Renommez les quatre noms (VerificateurCertificat, verifier_expiration, nom_hote, jours_restants), relancez la commande : elle doit répondre All checks passed!.

Ruff contrôle la forme : il ne sait pas qu'un nom est trompeur, ni que d ne dit rien. Ce jugement reste à la revue humaine, que traite la section suivante.

Comment discuter d'un nom en revue ?

Un commentaire de revue sur un nom propose une alternative et dit pourquoi. « Ce nom ne me plaît pas » n'aide personne ; « d ne dit pas que c'est une date d'expiration, je suggère date_expiration » donne le geste et la raison. La méthode générale de revue (linter, checklist, verdict) est dans la leçon Relire une pull request, à lire juste après celle-ci. Sa checklist vise les risques en exploitation et ne contient pas de question sur les noms : ajoutez-la vous-même, « les noms disent-ils ce que fait le code ? ».

Trois règles évitent les discussions sans fin. D'abord, la convention du projet l'emporte sur votre goût : si le dépôt écrit nb_ partout, ne l'abandonnez pas dans une seule fonction. Ensuite, renommer en masse dans la même pull request qu'une correction noie la vraie modification ; un renommage se propose dans une pull request à part. Enfin, un linter qui passe ne dispense pas de lire les noms : il a validé leur forme, jamais leur sens.

Et les noms des ressources cloud ?

Les ressources d'un cloud (machines, réseaux, bases) suivent leur propre convention, qui encode le type, l'environnement, le fournisseur et le lieu. Un exemple : vm-prd-aws-ew1-a-web-001 désigne une machine virtuelle de production, chez AWS, dans la région eu-west-1. La convention est détaillée avec ses abréviations et son lien avec les étiquettes dans la leçon Garde-fous, héritage des politiques et étiquetage, section sur l'étiquetage. Retenez ici l'idée commune avec le code : un nom prévisible se lit sans documentation et s'exploite par script.

Et les noms dans une base de données ?

Dans une base relationnelle, le choix compte moins que sa constance. Une convention répandue met les tables au singulier (utilisateur), les colonnes en snake_case (date_creation, client_id) et un préfixe pour les objets annexes, comme fk_ pour une clé étrangère (une colonne qui renvoie à la clé d'une autre table) ou idx_ pour un index (une structure qui accélère les recherches sur une colonne). Le singulier ou le pluriel se débat ; l'essentiel est de choisir et documenter, puis de s'y tenir. Les deux préfixes se lisent dans cet exemple PostgreSQL, qui ajoute une table certificat reliée à utilisateur :

CREATE TABLE utilisateur (
    utilisateur_id SERIAL PRIMARY KEY,
    nom VARCHAR(100),
    email VARCHAR(255) UNIQUE,
    date_creation TIMESTAMP DEFAULT now()
);

CREATE TABLE certificat (
    certificat_id SERIAL PRIMARY KEY,
    utilisateur_id INTEGER NOT NULL,
    date_expiration DATE NOT NULL,
    CONSTRAINT fk_certificat_utilisateur
        FOREIGN KEY (utilisateur_id) REFERENCES utilisateur (utilisateur_id)
);

CREATE INDEX idx_certificat_date_expiration ON certificat (date_expiration);

PRIMARY KEY désigne la colonne qui identifie chaque ligne de sa table. Les colonnes de ces tables se lisent sans commentaire, et la clé utilisateur_id se retrouve à l'identique dans les tables qui la référencent. La lecture d'un schéma existant est traitée dans Lire le schéma d'une base PostgreSQL.

À retenir

• Un nom est la première documentation du code : le relecteur le lit avant la logique.
• PEP 8 : snake_case pour variables et fonctions, PascalCase pour les classes, MAJUSCULES pour les constantes, minuscules pour les fichiers.
• Un bon nom dit le contenu, l'unité ou l'action ; il évite les noms génériques et les abréviations privées.
• Les branches Git portent un préfixe (feature/, fix/, chore/) et une description courte en minuscules.
• Ruff contrôle la forme des noms avec les règles N ; la revue juge leur sens, avec un commentaire qui propose une alternative.
• La convention du projet prime sur le goût personnel, et un renommage en masse se fait dans une pull request séparée.
• Ressources cloud et bases de données suivent la même logique : une convention unique, documentée, appliquée par le code.

Contrôle de connaissances

Vérifiez que l'essentiel de ce guide est acquis. Les questions portent uniquement sur ce qui vient d'être expliqué ici.

Contrôle de connaissances

Validez vos connaissances avec ce quiz interactif

6 questions

6 min.

70% requis

Informations

• Le chronomètre démarre au clic sur Démarrer
• Questions à choix multiples, vrai/faux et réponses courtes
• Vous pouvez naviguer entre les questions
• Les résultats détaillés sont affichés à la fin

Démarrer le quiz

Lance le quiz et démarre le chronomètre

×

📖 Voir la documentation →