# Fonctions et effets de bord

Ce cours traite du problème numéro un du projet : **des fonctions qui modifient plein de variables sans qu'on le voie**.

## Le problème

Voici `Unit.move`, simplifiée :

```python
def move(self, tile):
    ...
    self.current_movement -= TILES_MOVEMENT_COST[tile.type]
    self.tile_linked.unit = None
    self.tile_linked = tile
    tile.unit = self

    self.game.map.selected_tile = tile
    self.game.ui.button_handler.look_selected_tile(self.game.map.selected_tile)
```

Le nom dit « déplacer une unité ». Les quatre premières lignes le font. Les deux dernières changent la sélection du joueur et ouvrent ou ferment des panneaux à l'écran. Rien dans le nom ni dans les paramètres ne l'annonce.

## La notion : l'effet de bord

Une fonction peut faire deux choses :

- **renvoyer** une valeur ;
- **modifier** quelque chose à l'extérieur d'elle : c'est un **effet de bord**.

<Mermaid
  chart={`flowchart LR
    subgraph pure [Fonction pure]
      direction LR
      i1[paramètres] --> f1[fonction] --> o1[résultat]
    end
    subgraph impure [Fonction avec effets de bord]
      direction LR
      i2[paramètres] --> f2[fonction] --> o2[résultat]
      f2 -.-> e1[modifie un objet]
      f2 -.-> e2[écrit un fichier]
      f2 -.-> e3[change l'écran]
      g[état extérieur] -.-> f2
    end`}
/>

Une **fonction pure** ne dépend que de ses paramètres et ne modifie rien. Appelée deux fois avec les mêmes valeurs, elle rend le même résultat.

```python
def find_neighbors(coo):          # pure
    ...
    return neighbors

def hex_distance(a, b):           # pure
    ...
    return distance
```

Les effets de bord ne sont pas interdits. Un jeu **doit** modifier son état et dessiner à l'écran. Le but est de les rendre **peu nombreux et prévisibles**.

## Pourquoi les fonctions pures sont précieuses

| Qualité | Fonction pure | Fonction avec effets de bord |
| --- | --- | --- |
| Comprendre | On lit la fonction, c'est tout | Il faut connaître tout ce qu'elle touche |
| Tester | Une ligne : entrée, résultat attendu | Il faut préparer un jeu complet |
| Réutiliser | Partout | Seulement dans le même contexte |
| Déboguer | Le bug est dedans | Le bug peut venir de n'importe quel état extérieur |

## L'état global, même déguisé

Python a le mot-clé `global`. Le projet ne l'utilise pas. Mais chaque classe garde `self.game`, qui donne accès à tout :

```python
self.game.map.player_handler.players[self.owner].units_owned.remove(self)
```

Du point de vue de celui qui lit, le résultat est le même qu'une variable globale : **n'importe quelle fonction peut modifier n'importe quelle donnée**. Pour savoir qui change `selected_tile`, il faut chercher dans tout le projet. La réponse : six fonctions, dans deux fichiers, dont aucun n'est celui de la carte.

## Quatre techniques pour s'en sortir

### 1. Séparer le calcul de l'action

Une fonction qui calcule, une fonction qui applique.

```python
# avant : calcule ET dessine
def draw_build_tiles(self):
    self.allowed_construction_tiles = []
    for tile in self.tiles:
        if tile.owner == "1" and tile.type in BUILDINGS_TILE_CONDITION[...] and tile.building is None:
            self.allowed_construction_tiles.append(tile)
    ...  # dessin

# après : une fonction pure pour la règle
def allowed_build_coos(world, player_id, building_name):
    return [
        tile.coo for tile in world.tiles()
        if tile.owner_id == player_id
        and tile.terrain in BUILDINGS[building_name]["terrains"]
        and tile.building is None
    ]
```

La seconde version sert au joueur, au bot et aux tests. Elle ne dessine rien.

### 2. Passer ce dont on a besoin en paramètre

Au lieu d'aller chercher dans `self.game`, on reçoit.

```python
# avant
def move_unit(self, tile):
    selected_unit = self.game.map.selected_tile.unit

# après
def move_unit(self, unit, tile):
```

La signature devient honnête : elle dit de quoi la fonction a besoin. Et le bot peut l'appeler avec **son** unité.

### 3. Renvoyer un résultat plutôt que modifier en cachette

```python
# avant : ne dit rien, le clic n'a parfois aucun effet
def move(self, tile):
    if tile in neighbors:
        if tile.unit == None and ...:
            ...

# après : celui qui appelle sait ce qui s'est passé
def move(self, tile):
    if tile not in neighbors:
        return MoveResult.TOO_FAR
    if self.current_movement < cost:
        return MoveResult.NOT_ENOUGH_MOVEMENT
    ...
    return MoveResult.OK
```

L'interface peut alors afficher un message au joueur.

### 4. Un seul propriétaire par donnée

Chaque donnée appartient à un objet, et **lui seul** la modifie. Les autres passent par ses méthodes.

```python
# avant : trois endroits modifient la liste d'un joueur
self.game.map.player_handler.players[self.owner].units_owned.remove(self)

# après : le joueur gère sa liste
player.remove_unit(unit)
```

## Commande et requête

Une règle simple à garder en tête : une fonction **répond à une question** ou **change quelque chose**, pas les deux.

| Type | Renvoie | Modifie | Exemple |
| --- | --- | --- | --- |
| Requête | Une valeur | Rien | `get_settler_possibilities()` |
| Commande | Un compte rendu | L'état | `finish_turn()` |

`look_selected_tile` fait les deux : selon le cas elle sélectionne une case, ouvre un panneau, ou construit un bâtiment. D'où la difficulté à la nommer.

## Dans le jeu : avant, après

<Mermaid
  chart={`flowchart TB
    subgraph avant [Aujourd'hui]
      a1[Unit.move] --> a2[tile.unit]
      a1 --> a3[map.selected_tile]
      a1 --> a4[panneaux de l'écran]
      a1 --> a5[curseur]
    end
    subgraph apres [Après]
      b1[move_unit] --> b2[tile.unit]
      b1 --> b3[renvoie MoveResult]
      b3 --> b4[l'interface met à jour<br/>sa sélection et ses panneaux]
    end`}
/>

## À retenir

- Un effet de bord, c'est tout ce qu'une fonction modifie en dehors d'elle.
- `self.game` partout revient à une variable globale.
- Séparer **calculer** et **appliquer**.
- Les paramètres disent de quoi la fonction a besoin, la valeur de retour dit ce qui s'est passé.
- Une donnée, un propriétaire.

## Exercices

1. Dans `units.py`, lister tout ce que modifie `Settler.special_action`. Combien d'objets différents ?
2. Écrire la fonction pure `allowed_build_coos` ci-dessus à partir de `Map.draw_build_tiles`, et l'utiliser dans cette dernière.
3. Chercher `selected_tile =` dans tout le projet. Qui devrait être le seul à la modifier ?
4. Faire renvoyer `True` ou `False` à `Unit.move` selon que le déplacement a eu lieu. Où ce résultat serait-il utile ?
