Aller au contenu

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
if (self.ui.page_handler.page == 5) and (not button_clicked):

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_with_prio. 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émentConventionExemple
Variable, fonction, méthodesnake_caseselected_tile, find_neighbors
ClassePascalCasePlayerHandler, Tile
ConstanteMAJUSCULES_AVEC_TIRETS_BASMAX_LAYERS
Module, fichiersnake_case, courtsaves_handler.py
Usage interneun tiret bas devant_rebuild_path

Le projet respecte déjà presque tout. Deux écarts : UI_Handler, Saves_Handler 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 jeuCe que c'est vraimentNom plus clair
tile_with_prioLa case sous la sourishovered_tile
cooDes coordonnées de grillecoord, ou coo si le projet entier l'utilise
add_decalageConvertit des coordonnées odd-r en positionoffset_to_position
nSelon l'endroit : un index, un nombre, une listeLe 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
# avant if self.ui.page_handler.page == 5: # après if self.ui.page_handler.page == Page.GAME:

Avec une énumération :

Python
from enum import Enum class Page(Enum): START = 0 OPTIONS = 1 NEW_OR_LOAD = 2 SAVES = 3 GAME_SETUP = 4 GAME = 5 TUTORIAL = 6

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 jeuCe qu'elle faitNom plus clair
layers(n)Crée les anneaux de coordonnéesbuild_layers
button_color()Passe à la couleur suivantecycle_button_color
death()Retire l'unité du jeudie ou remove_from_game
look_selected_tile(tile)Sélectionne, ou construit, selon le casDeux fonctions : select_tile, place_building

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
# avant self.playing = True self.pause = False bool = not self.ui.page_handler.moving_unit # après self.is_running = True self.is_paused = False should_move = not self.ui.page_handler.is_moving_unit

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.__init__ et id dans Player.__init__.

5. Une seule langue, une seule orthographe

Le code mélange anglais et français : get_tiles_frequences, add_decalage, "arrondissement_bords_boutons", 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
# avant self.tile_with_prio = None # la tile survolée par la souris # après self.hovered_tile = None

Un commentaire utile explique pourquoi, pas quoi. Le projet en contient de très bons :

Python
return neighors[parity] # comme les hexagones sont décalés 1 ligne sur 2, # les voisins sont différents si la ligne est paire ou impaire

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

  1. Trouver toutes les comparaisons page == dans ui.py et map.py. Créer l'énumération Page et les remplacer.
  2. Renommer tile_with_prio avec l'outil de renommage de l'éditeur. Lancer le jeu pour vérifier.
  3. Lister cinq noms du projet que vous ne comprenez pas sans lire le code. Proposer un meilleur nom pour chacun.