Nommer les choses
On lit du code bien plus souvent qu'on en écrit. Un bon nom évite d'avoir à lire le reste pour comprendre.
Le problème
Voici une ligne de ui.py :
Python
Que veut dire 5 ? Il faut chercher ailleurs pour apprendre que c'est l'écran de jeu. Ce test apparaît plus de vingt fois dans le projet.
Autre exemple, dans map.py : tile_. Prioritaire pour quoi ? En lisant le code, on comprend que c'est la case survolée par la souris.
Les conventions de Python
Python a un guide de style officiel, la PEP 8. Les règles de nommage tiennent en un tableau.
| Élément | Convention | Exemple |
|---|---|---|
| Variable, fonction, méthode | snake_case | selected_, find_ |
| Classe | PascalCase | PlayerHandler, Tile |
| Constante | MAJUSCULES_ | MAX_LAYERS |
| Module, fichier | snake_case, court | saves_ |
| Usage interne | un tiret bas devant | _rebuild_ |
Le projet respecte déjà presque tout. Deux écarts : UI_Handler, Saves_ et AI_Player mélangent les deux styles. En PascalCase : UiHandler, SavesHandler, AiPlayer.
Cinq règles pratiques
1. Un nom dit ce que c'est, pas comment c'est fait
| Dans le jeu | Ce que c'est vraiment | Nom plus clair |
|---|---|---|
tile_ | La case sous la souris | hovered_tile |
coo | Des coordonnées de grille | coord, ou coo si le projet entier l'utilise |
add_decalage | Convertit des coordonnées odd-r en position | offset_ |
n | Selon l'endroit : un index, un nombre, une liste | Le nom de ce que ça contient |
2. Pas de nombre magique
Un nombre écrit en dur dans une condition n'explique rien. On lui donne un nom.
Python
Avec une énumération :
Python
Même chose pour "1", l'identifiant du joueur humain, répété dans plusieurs fichiers.
3. Une fonction commence par un verbe
Une fonction fait quelque chose. Son nom doit le dire.
| Dans le jeu | Ce qu'elle fait | Nom plus clair |
|---|---|---|
layers(n) | Crée les anneaux de coordonnées | build_layers |
button_ | Passe à la couleur suivante | cycle_ |
death() | Retire l'unité du jeu | die ou remove_ |
look_ | Sélectionne, ou construit, selon le cas | Deux fonctions : select_tile, place_ |
Le dernier cas est le plus instructif : quand on n'arrive pas à nommer une fonction, c'est souvent qu'elle fait deux choses.
4. Les booléens se lisent comme une question
Un booléen répond par oui ou non. On le préfixe par is_, has_, can_.
Python
Attention à bool, type, id, list : ce sont des noms de Python. Les utiliser comme variable ou paramètre masque la fonction d'origine. Le projet le fait avec bool dans ui.py, type dans Tile.__ et id dans Player.__.
5. Une seule langue, une seule orthographe
Le code mélange anglais et français : get_, add_decalage, "arrondissement_, ressource avec deux s. Le plus simple est de choisir l'anglais pour le code, puisque Python et Pygame le sont, et de garder le français pour les commentaires.
Une faute dans un nom se propage : PageHanlder est écrit ainsi partout où il sert.
Les commentaires ne remplacent pas un bon nom
Python
Un commentaire utile explique pourquoi, pas quoi. Le projet en contient de très bons :
Python
Renommer sans rien casser
Renommer à la main dans dix fichiers est risqué. Les éditeurs le font proprement :
- Dans VS Code : placer le curseur sur le nom, appuyer sur F2.
- Faire un commit juste avant, et un commit juste après, contenant uniquement le renommage.
À retenir
- Un nom dit ce que c'est.
- Pas de nombre ni de chaîne magique : une constante ou une énumération.
- Verbe pour une fonction, question pour un booléen.
- Si une fonction est impossible à nommer, elle fait trop de choses.
Exercices
- Trouver toutes les comparaisons
page ==dansui.pyetmap.py. Créer l'énumérationPageet les remplacer. - Renommer
tile_avec l'outil de renommage de l'éditeur. Lancer le jeu pour vérifier.with_ prio - Lister cinq noms du projet que vous ne comprenez pas sans lire le code. Proposer un meilleur nom pour chacun.