Petit manuel illustré, à l'usage de qui écrit du code lu par d'autres
Sept principes à manipuler soi-même, et leur lexique · édition nº 1
Ce manuel n'apprend pas à coder. Il parle de la différence entre du code qui marche et du code qu'on aime retrouver le lundi matin.
Une variable ne s'appelle jamais x par hasard : elle s'appelle
x parce qu'au moment de l'écrire, on ne savait pas encore très bien
ce qu'elle était. Le nom est le premier brouillon de la pensée.
Tirez le curseur, et regardez ce que ça change pour la personne qui lira.
const x = heures / 24;
« Le code est lu dix fois plus souvent qu'il n'est écrit. »
C'est pour le lecteur qu'on écrit. Le compilateur, lui, se moque de tout.
Une fonction de quatre-vingts lignes n'est pas une fonction : c'est un chapitre sans titre ni paragraphes. La découper, ce n'est pas la raccourcir, c'est donner un nom à chacune de ses idées. Essayez.
function inscrire(client) { // 1. vérifier l'email, le mot de passe, // l'âge, les doublons... (18 lignes) ⋮ // 2. écrire en base, gérer les erreurs, // réessayer deux fois... (24 lignes) ⋮ // 3. composer l'email de bienvenue, // l'envoyer, journaliser... (31 lignes) ⋮ }
Chaque if imbriqué enfonce le lecteur d'un étage : il doit retenir
toutes les conditions au-dessus de sa tête. Traiter d'abord les cas qui ne
concernent pas la suite, et s'en débarrasser par un return,
c'est laisser le chemin principal au rez-de-chaussée.
function servir(client) { if (client) { if (client.estMajeur) { if (!client.estBanni) { if (bar.estOuvert) { return verser(client); } } } } }
Un nombre posé nu dans le code est une devinette laissée au suivant. Celui-ci vous nargue depuis tout à l'heure : cliquez dessus pour lever le sort.
if (age > ) { purgerLeCache(entree); }
« Écris ton code comme si la personne qui devra le maintenir était un violent psychopathe qui sait où tu habites. »
Adage de bureau, auteur prudemment anonyme.
Copier-coller un bloc de code, c'est faire une promesse silencieuse : « je corrigerai les deux ». Personne ne tient cette promesse. Faites avancer le temps et regardez les jumeaux cesser de l'être.
facture.js
total = prix * quantite; tva = total * 0.20; net = total + tva;
devis.js copié le 12 mars
total = prix * quantite; tva = total * 0.20; net = total + tva;
Les scouts la formulent ainsi : laisse le campement plus propre que tu ne l'as trouvé. Pas de grand nettoyage héroïque, pas de refonte : juste une vitre ressoudée en passant. Le code sur lequel vous travaillez a douze carreaux. Certains sont fêlés. Vous savez quoi faire.
Devant un problème simple, l'ingénieur inspiré voit une occasion d'architecture. Le besoin du jour : appliquer une remise de 10 % aux bons clients. Comparez les deux réponses.
class AbstractDiscountPolicyFactory { … } class PercentageDiscountStrategyImpl extends BaseDiscountStrategy { … } class DiscountStrategyResolverRegistry { … } interface DiscountEligibilityVisitor { … } // 6 fichiers, 214 lignes, 1 diagramme UML, // et toujours pas de remise appliquée
Les mêmes idées, dans la langue des entretiens d'embauche.
Une part croissante du code est écrite par des agents IA, et un agent écrit comme on le lui demande. Voici les sept principes de ce manuel compilés en règles d'agent : déposez le fichier dans votre projet, et vos machines prendront de bonnes manières.
.claude/skills/clean-code/
AGENTS.md
universel · à la racine du projet (Codex, Claude, etc.)
regles-cursor.mdc
Cursor · à poser dans .cursor/rules/
chargement…