Le code est écrit une fois et lu cent fois. Il doit se lire comme de la prose claire.
⏱️ Durée : environ 80 minutes · 🎓 Niveau : intermédiaire · 🏅 Badge : Artisan du code lisible
🎬 L'histoire
Kodi relit une fonction écrite il y a six mois par… lui-même :
def f(d, t):
r = 0
for x in d:
if x[2] > t and x[3] != 0:
r += x[1] * 0.2
return r
« Qui est
d? Que vautx[2]? D'où sort ce 0.2 ? » se demande-t-il. « Ton futur toi est un collègue qui n'a pas ta mémoire, dit Sam. Écris pour lui. »
Tu apprends les pratiques qui rendent un code immédiatement compréhensible.
🎯 Ta mission
À la fin, je serai capable de :
- choisir des noms qui révèlent l'intention
- écrire de petites fonctions qui font une chose
- remplacer les nombres magiques par des constantes nommées
- simplifier la logique avec des retours anticipés
- écrire des commentaires utiles (le pourquoi, pas le quoi)
🧩 Défi d'échauffement (5 XP)
Tu lis deux phrases : (A) « Appliquer la remise de fidélité aux clients qui ont plus de 2 ans d'ancienneté. » (B) « Faire x = y * 0,85 pour z dans la liste q si w > 2. » Quelle phrase comprends-tu tout de suite ? Qu'est-ce qui rend l'autre obscure ? Liste trois règles pour qu'un texte (ou un code) soit facile à lire.
💡 Le concept
1. Des noms qui disent l'intention
| ❌ | ✅ |
|---|---|
d | membres |
lst2 | membres_actifs |
process(x) | calculer_remise_fidelite(membre) |
flag | est_abonne |
Règles : prononçables, cherchables, sans abréviations obscures, un mot par concept. Un booléen se nomme comme une question (est_, a_, peut_). Une fonction est un verbe, une classe un nom.
2. Des fonctions petites, qui font une chose
- Une fonction = une idée, un niveau d'abstraction.
- Peu de paramètres (idéalement ≤ 3). Au-delà : regrouper dans un objet.
- Éviter les paramètres booléens qui changent le comportement (
envoyer(msg, True)) : deux fonctions plus claires.
3. Pas de nombres magiques
# ❌
if age >= 18 and score > 60: ...
# ✅
AGE_MAJORITE = 18
SCORE_MINIMUM = 60
if age >= AGE_MAJORITE and score > SCORE_MINIMUM: ...
4. La logique plate
Les if imbriqués sur plusieurs niveaux fatiguent. Traite les cas d'erreur d'abord (retours anticipés / guard clauses), puis le cas principal.
def remise(membre):
if membre is None:
return 0
if not membre.actif:
return 0
if membre.anciennete < 2:
return 0
return 0.15
5. Les commentaires
- Un commentaire qui répète le code est du bruit :
i += 1 # incrémente i. - Un bon commentaire explique le pourquoi : une règle métier, une contrainte, un piège.
- Si tu ressens le besoin d'un commentaire pour expliquer quoi, renomme ou extrais une fonction.
- Les docstrings documentent le contrat (paramètres, retour, erreurs).
6. La gestion des erreurs
- Lever des exceptions précises plutôt que renvoyer
Noneou-1ambigus. - Ne pas avaler une exception avec un
except:vide. - Messages d'erreur utiles : quoi, avec quelle valeur, quelle attente.
7. Le formatage et les outils
Un style cohérent facilite la lecture : un formateur automatique (black) et un analyseur (ruff, flake8) évitent les discussions sans fin. Les tests documentent aussi le comportement.
8. La règle du boy-scout
Laisse le code un peu plus propre que tu ne l'as trouvé.
De petites améliorations constantes évitent la dégradation lente.
🔍 Exemple pas à pas
Problème : rendre le code de Kodi lisible.
Avant :
def f(d, t):
r = 0
for x in d:
if x[2] > t and x[3] != 0:
r += x[1] * 0.2
return r
On découvre (en lisant le code appelant) que d est une liste de ventes (id, montant, anciennete_en_jours, actif), t un seuil d'ancienneté, et 0,2 le taux de commission.
Après :
from dataclasses import dataclass
TAUX_COMMISSION = 0.20
@dataclass
class Vente:
identifiant: int
montant: float
anciennete_jours: int
est_active: bool
def est_eligible(vente, anciennete_minimum_jours):
return vente.est_active and vente.anciennete_jours > anciennete_minimum_jours
def commission(vente):
return vente.montant * TAUX_COMMISSION
def total_commissions(ventes, anciennete_minimum_jours):
"""Somme des commissions des ventes actives plus anciennes que le seuil."""
return sum(commission(v) for v in ventes if est_eligible(v, anciennete_minimum_jours))
ventes = [Vente(1, 100, 30, True), Vente(2, 200, 5, True), Vente(3, 50, 90, False)]
assert total_commissions(ventes, 10) == 20.0
print(total_commissions(ventes, 10))
Vérification d'équivalence :
def f(d, t):
r = 0
for x in d:
if x[2] > t and x[3] != 0:
r += x[1] * 0.2
return r
anciennes = [(1, 100, 30, 1), (2, 200, 5, 1), (3, 50, 90, 0)]
nouvelles = [Vente(i, m, a, bool(act)) for i, m, a, act in anciennes]
assert f(anciennes, 10) == total_commissions(nouvelles, 10)
Ce qui a changé : les noms racontent le métier ; le 0,2 a un nom ; les règles d'éligibilité et de commission sont séparées donc modifiables indépendamment ; la fonction principale se lit comme une phrase : total des commissions des ventes éligibles.
Un bon et un mauvais commentaire :
# mauvais : répète le code
total = prix * quantite # multiplie prix et quantité
# bon : explique une règle non évidente
# Les ventes de moins de 5 jours peuvent encore être annulées (délai légal de rétractation).
DELAI_RETRACTATION_JOURS = 5
✍️ À toi, avec aide (10 XP)
Rends ce code lisible :
def g(l, a):
o = []
for i in l:
if i["a"] >= a:
if i["s"] == 1:
o.append(i["n"].upper())
return o
On sait que l est une liste de membres (n nom, a âge, s statut où 1 = actif) et a un âge minimum.
- Donne de bons noms.
- Aplatis la logique.
- Écris un test d'équivalence.
💡 Indice 1
Introduis une fonction est_membre_eligible(membre, age_minimum).
💡 Indice 2
Remplace le statut 1 par une constante STATUT_ACTIF.
💡 Indice 3
Une compréhension de liste exprime bien « les noms en majuscules des membres éligibles ».
✅ Réponse
STATUT_ACTIF = 1
def est_membre_eligible(membre, age_minimum):
return membre["a"] >= age_minimum and membre["s"] == STATUT_ACTIF
def noms_en_majuscules_des_membres_eligibles(membres, age_minimum):
return [m["n"].upper() for m in membres if est_membre_eligible(m, age_minimum)]
def g(l, a):
o = []
for i in l:
if i["a"] >= a:
if i["s"] == 1:
o.append(i["n"].upper())
return o
membres = [{"n": "ada", "a": 30, "s": 1}, {"n": "bob", "a": 17, "s": 1}, {"n": "cleo", "a": 40, "s": 0}]
assert noms_en_majuscules_des_membres_eligibles(membres, ) == g(membres, ) == []
()
🚀 À toi, en solo (20 XP)
Revue de lisibilité. Voici une fonction avec de nombreux défauts :
def proc(x, y, z=False):
# calcule
if x != None:
if len(x) > 0:
t = 0
for i in range(len(x)):
if x[i]["p"] > 100:
t = t + x[i]["p"] * 0.9
else:
t = t + x[i]["p"]
if z == True:
t = t + y
return t
else:
return -1
else:
return -1
- Liste au moins 8 problèmes de lisibilité.
- Réécris-la proprement (noms, constantes, retours anticipés, paramètre booléen remplacé, erreurs explicites).
- Prouve l'équivalence sur les cas valides et explique ce que tu as volontairement changé (le
-1).
✅ Pistes de correction
Problèmes : noms obscurs (proc, x, y, z, t, i) ; commentaire inutile ; != None au lieu de is not None ; imbrication ; range(len(...)) au lieu d'itérer directement ; nombres magiques (100, 0,9) ; z == True ; paramètre booléen qui change le comportement ; -1 ambigu pour signaler une erreur.
SEUIL_REMISE = 100
TAUX_REMISE = 0.10
def prix_remise(prix):
return prix * (1 - TAUX_REMISE) if prix > SEUIL_REMISE else prix
def total_panier(articles):
"""Total d'un panier non vide ; une remise de 10 % s'applique aux articles de plus de 100."""
if not articles:
raise ValueError("le panier est vide")
return sum(prix_remise(a["p"]) a articles)
():
total_panier(articles) + frais_livraison
():
x != :
(x) > :
t =
i ((x)):
x[i][] > :
t = t + x[i][] *
:
t = t + x[i][]
z == :
t = t + y
t
:
-
:
-
panier = [{: }, {: }, {: }]
total_panier(panier) == proc(panier, ) ==
total_avec_livraison(panier, ) == proc(panier, , ) ==
:
total_panier([])
ValueError e:
(, e)
⚠️ Pièges classiques
| Piège | Pourquoi c'est un problème | Comment l'éviter |
|---|---|---|
| Noms trop courts ou trompeurs | Il faut deviner l'intention | Nom = intention, pas type |
| Commentaires qui répètent le code | Bruit, et ils deviennent faux | Commenter le pourquoi |
| Fonctions de 100 lignes | Plusieurs idées mélangées | Extraire des fonctions nommées |
Renvoyer -1 ou None pour une erreur | Confusion avec une vraie valeur | Lever une exception explicite |
🐉 Mini-boss (40 XP)
Chantier de nettoyage. Écris (volontairement mal) un script de 60 lignes qui traite des commandes : lecture d'une liste de dictionnaires, validation, calcul de remises selon le client et la quantité, calcul de TVA, arrondi, et génération d'un récapitulatif texte.
- Écris les tests qui figent son comportement (au moins 10 cas).
- Réécris-le en appliquant toutes les pratiques de la mission (noms, fonctions courtes, constantes, retours anticipés, exceptions, docstrings).
- Vérifie que les tests passent toujours.
- Mesure avec l'outil d'audit de la mission 1 : complexité, longueur, imbrication avant/après.
- Rédige 5 lignes : quelles améliorations ont eu le plus d'effet sur la lisibilité ?
✅ Pistes de correction
Un bon travail : fonctions valider_commande, taux_remise, calculer_ht, calculer_tva, formater_recapitulatif, chacune avec une docstring d'une ligne ; constantes TAUX_TVA, SEUIL_QUANTITE, REMISES_PAR_CLIENT ; exceptions CommandeInvalide avec message précis ; tests d'équivalence parametrés ; mesures montrant la baisse de la complexité maximale (par exemple de 14 à 4) et de la profondeur d'imbrication (de 5 à 2). Les améliorations les plus efficaces sont généralement le renommage et l'extraction de fonctions nommées d'après l'intention.
⚡ Quiz éclair (15 XP si 4/5 ou plus)
1. Un bon nom de fonction est généralement :
- A. un verbe qui exprime l'intention
- B. une lettre
- C. un nombre
2. Les retours anticipés servent à :
- A. accélérer le code
- B. réduire l'imbrication
- C. supprimer les tests
3. Un bon commentaire explique :
- A. le quoi évident
- B. la syntaxe
- C. le pourquoi
4. 🔁 Révision mission 03 : Le principe ouvert/fermé dit :
- A. ouvert à l'extension, fermé à la modification
- B. ouvert à la modification, fermé à l'extension
- C. tout est ouvert
5. 🔁 Révision mission 03 : Inverser les dépendances, c'est :
- A. supprimer les dépendances
- B. dépendre d'abstractions plutôt que de détails
- C. tout mettre dans une classe
✅ Réponses
- A.
- B.
- C.
- A.
- B.
🪞 Je réfléchis (10 XP)
- Quel nom de variable ou de fichier dans ton travail ne dit pas ce qu'il fait ?
- Comment la règle du boy-scout pourrait-elle s'appliquer à tes projets ?
🎒 À retenir
- Noms qui révèlent l'intention.
- Petites fonctions, une idée chacune.
- Constantes nommées, pas de nombres magiques.
- Retours anticipés, logique plate.
- Commenter le pourquoi ; exceptions explicites.
flowchart LR
T(["Clean Code : écrire pour être lu"])
T --> R1["1. Noms qui révèlent l'intention."]
T --> R2["2. Petites fonctions, une idée chacune."]
T --> R3["3. Constantes nommées, pas de nombres magiques."]
T --> R4["4. Retours anticipés, logique plate."]
T --> R5["5. Commenter le pourquoi ; exceptions explicites."]
Description du schéma : la mission au centre, reliée aux cinq idées à retenir.
🏅 Récompenses
Total possible : 100 XP · 🏅 Badge Artisan du code lisible
← Mission 03 — Les principes SOLID · Mission 05 — Interfaces et abstractions →
HEF-080 — Génie logiciel

