# 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ément | Convention | Exemple |
| --- | --- | --- |
| Variable, fonction, méthode | `snake_case` | `selected_tile`, `find_neighbors` |
| Classe | `PascalCase` | `PlayerHandler`, `Tile` |
| Constante | `MAJUSCULES_AVEC_TIRETS_BAS` | `MAX_LAYERS` |
| Module, fichier | `snake_case`, court | `saves_handler.py` |
| Usage interne | un 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 jeu | Ce que c'est vraiment | Nom plus clair |
| --- | --- | --- |
| `tile_with_prio` | 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_to_position` |
| `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
# 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 jeu | Ce qu'elle fait | Nom plus clair |
| --- | --- | --- |
| `layers(n)` | Crée les anneaux de coordonnées | `build_layers` |
| `button_color()` | Passe à la couleur suivante | `cycle_button_color` |
| `death()` | Retire l'unité du jeu | `die` ou `remove_from_game` |
| `look_selected_tile(tile)` | Sélectionne, ou construit, selon le cas | Deux 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.
