Comment Écrire des Fonctions Lisibles ?

C’est un scénario classique : il est 2h du matin, le café est froid, et vous luttez pour comprendre une fonction que vous avez écrite… il y a à peine 24 heures. Le code fonctionne, mais il est illisible, tortueux, et ressemble à une énigme. Ce problème n’est pas lié à votre intelligence, mais à la façon dont le code est structuré. Heureusement, avec quelques principes simples, vous pouvez écrire des fonctions claires et compréhensibles, même à 3h du matin sous la pression d’un délai. Voici comment.

Le Principe Fondateur : Une Fonction, Une Chose

C’est la règle d’or, le « premier commandement » du code lisible. Une fonction doit faire une chose et une seule, et la faire bien.

À quoi ça ressemble ? Au lieu d’une fonction traiterCommande() qui valide, calcule la TVA, met à jour la base de données, envoie un email et génère un PDF, vous aurez plusieurs fonctions :
- validerCommande(commande)
- calculerPrixFinal(commande)
- sauvegarderCommande(commande)
- notifierClient(commande)
Pourquoi ça aide à 2h du matin ? Lorsque vous relisez le code, vous pouvez comprendre la logique globale en un coup d’œil en lisant les noms des fonctions appelées. Si un bug survient, vous savez exactement dans quelle petite fonction isolée chercher.

Règle #1 : Donnez des Noms qui Révèlent l’Intention, Pas l’Implémentation

Le nom d’une fonction est votre premier et meilleur outil de documentation.

Mauvais nom : faireTruc(donnees), process(), update().
Bon nom : calculerTVA(panier), estUtilisateurActif(utilisateur), formaterDatePourAffichage(timestamp).
Astuce du « 2h du matin » : Demandez-vous : « Si je devais expliquer ce que fait cette fonction à un collègue endormi, quels mots j’utiliserais ? » Utilisez ces mots. Préférez les verbes concrets. Cliquez ici pour explorer ce sujet en détail.

Règle #2 : Réduisez drastiquement le Nombre de Paramètres

Une fonction avec trop de paramètres est un cauchemar à comprendre et à utiliser. La limite magique est souvent 3.

Pourquoi ? À 2h du matin, votre cerveau ne veut pas jongler avec l’ordre de 7 arguments. De plus, une longue liste de paramètres est souvent le signe que la fonction fait trop de choses.
Comment corriger ?
1. Regroupez les paramètres liés dans un objet ou une structure de données. Au lieu de creerUtilisateur(nom, prenom, email, rue, ville, codePostal), utilisez creerUtilisateur(infosPersonnelles, adresse).
2. Extrayez une partie de la logique dans une nouvelle fonction qui nécessite moins de paramètres.

Règle #3 : Le Corps de la Fonction Doit Être Court et Descendant

Imaginez que votre fonction est un article de journal.

Le titre = Le nom de la fonction.
Le chapeau = Les premiers niveaux d’abstraction (les appels à d’autres fonctions bien nommées).
Les détails = Le code de bas niveau, plus loin dans la fonction.
La technique : Structurez votre fonction en niveaux d’abstraction décroissants. Placez les grandes étapes logiques en haut, sous forme d’appels à des fonctions de niveau inférieur. Ces fonctions elles-mêmes contiendront les détails.

Exemple à 2h du matin :

# Niveau haut, très lisible
def traiterCommande(commande):
    if not estCommandeValide(commande):  # Étape 1 claire
        raise ErreurCommandeInvalide
    
    prix_final = calculerPrixFinal(commande)  # Étape 2 claire
    sauvegarderCommande(commande, prix_final) # Étape 3 claire
    notifierClient(commande)                  # Étape 4 claire

Chaque fonction appelée (estCommandeValide, calculerPrixFinal, etc.) cache un niveau de détail que vous n’avez pas besoin de comprendre tout de suite.

Règle #4 : Évitez les Effets de Bord Surprenants

Une fonction devrait faire ce que son nom promet, et rien de plus. Un effet de bord est une modification de l’état du système qui n’est pas l’objectif principal.

Exemple sournois : Une fonction trouverUtilisateurParId(id) qui, à la faveur de la recherche, met aussi en cache des données connexes.
Pourquoi c’est dangereux à 2h du matin ? Vous appelez une fonction pour une raison, et elle en profite pour faire autre chose en secret. C’est la source de bugs subtils et difficiles à tracer.
La solution : Soyez explicite. Si une fonction modifie quelque chose, faites-le apparaître dans son nom : trouverEtMettreEnCacheUtilisateur() est bien moins dangereux.

Règle #5 : Renvoyez Tôt, Utilisez des Gardes (Guard Clauses)

La structure « fail fast » (échec rapide) est votre alliée pour la lisibilité. Au lieu d’imbriquer toute votre logique dans une énorme condition if (toutEstOk), traitez les cas d’erreur dès le début de la fonction et quittez-la.

Code « Spaghetti » (À éviter) :

function accederAuSysteme(utilisateur, droits) {
  if (utilisateur != null) {
    if (utilisateur.estActif) {
      if (droits.includes('admin')) {
        // ... 30 lignes de logique principale ici ...
      } else {
        throw new Error('Droits insuffisants');
      }
    } else {
      throw new Error('Utilisateur inactif');
    }
  } else {
    throw new Error('Utilisateur non fourni');
  }
}

Code « Garde Clauses » (Lisible, même à 2h) :

function accederAuSysteme(utilisateur, droits) {
  if (!utilisateur) throw new Error('Utilisateur non fourni');
  if (!utilisateur.estActif) throw new Error('Utilisateur inactif');
  if (!droits.includes('admin')) throw new Error('Droits insuffisants');
  
  // ... 30 lignes de logique principale ICI, sans indentation profonde ...
}

Votre Checklist de Nuit

Avant de valider votre fonction, même épuisé, demandez-vous vite fait :

Son nom dit-elle CE QU’ELLE FAIT ? (pas comment)
A-t-elle PLUS DE 3 PARAMÈTRES ?
Puis-je la décrire SANS utiliser « et » ? (signe qu’elle fait une seule chose)
Un collègue endormi la comprendrait-il en 30 secondes ?

La Lisibilité, un Cadeau que vous vous Faites

Écrire des fonctions lisibles n’est pas une faveur pour les autres, c’est un cadeau que vous vous faites à vous-même, futur. C’est ce « vous » de 2h du matin, épuisé et confronté à un bug critique, qui bénéficiera d’un code clair, prévisible et facile à naviguer.

En appliquant ces règles simples, vous transformez votre codebase d’un champ de mines en une carte au trésor bien légendée. Vous gagnerez du temps, réduirez le stress et dormirez mieux. Après tout, le meilleur code est souvent celui que vous n’avez pas besoin de relire.