Nommer et organiser son code

Ce que tu vas apprendre

• Choisir des noms de variables et de fonctions qui expliquent ce qu'ils contiennent.
• Découper un long bloc de code en petites fonctions qui font une seule chose.
• Ranger tes fichiers dans une structure de dossiers que tu retrouves en six mois.

Un code se lit plus qu'il ne s'écrit

Tu écris une ligne une fois. Toi ou quelqu'un d'autre la relira dix fois. Un code propre est donc un code que l'on comprend vite.

Compare ces deux versions du même calcul, sur le site de recettes :

const x = r.filter(a => a.t < 30)

const recettesRapides = recettes.filter(recette => recette.dureeMinutes < 30)

La seconde se lit presque comme une phrase. Tu n'as pas besoin de deviner ce que x, r ou t signifient.

Des noms qui disent la vérité

Un nom est l'étiquette d'une variable, d'une fonction ou d'un fichier. Un bon nom répond à la question « qu'est-ce que c'est ? » sans qu'on lise le code autour.

Quelques règles simples :

1. Un nom précis plutôt qu'un nom court : prixTotal plutôt que p.
2. Une variable est un nom, une fonction est un verbe : recettes, chargerRecettes().
3. Un booléen se lit comme une question : estPublie, aDesIngredients.
4. Un seul style dans tout le projet.

Le style le plus courant en JavaScript est le camelCase : les mots sont collés, chaque mot après le premier prend une majuscule (dureeCuisson). Pour un composant ou une classe, on met aussi une majuscule au premier mot : CarteRecette.

Pas de nombres magiques

Un nombre magique est une valeur écrite directement dans le code, sans explication. Personne ne sait d'où elle vient.

if (recette.dureeMinutes < 30) {
  afficherBadge('rapide')
}

Que veut dire 30 ? Donne-lui un nom :

const DUREE_MAX_RECETTE_RAPIDE = 30

if (recette.dureeMinutes < DUREE_MAX_RECETTE_RAPIDE) {
  afficherBadge('rapide')
}

Si la limite change, tu modifies une seule ligne. Une valeur qui ne change jamais s'écrit par convention en MAJUSCULES avec des tirets bas.

Des fonctions petites

Une fonction est un bloc de code nommé que tu peux appeler plusieurs fois. Une bonne fonction fait une seule chose, et son nom dit laquelle.

Voici une fonction qui en fait trop :

function traiterRecette(recette) {
  const ingredients = recette.ingredients.map(i => i.trim().toLowerCase())
  const duree = recette.preparation + recette.cuisson
  document.querySelector('#titre').textContent = recette.titre
  return { ingredients, duree }
}

Elle nettoie des données, calcule une durée et modifie la page. Découpe-la :

function nettoyerIngredients(ingredients) {
  return ingredients.map(i => i.trim().toLowerCase())
}

function calculerDuree(recette) {
  return recette.preparation + recette.cuisson
}

Chaque morceau se teste, se relit et se réutilise seul. Si tu as du mal à nommer une fonction sans écrire « et » dans son nom, elle en fait trop.

Les commentaires expliquent le pourquoi

Un commentaire est une ligne ignorée par l'ordinateur, écrite pour les humains. Il ne doit pas répéter le code.

// Ajoute 1 à compteur
compteur++

Ce commentaire n'apprend rien. Un bon commentaire donne la raison d'un choix qui n'est pas évident :

// L'API renvoie les durées en secondes, on convertit en minutes.
const dureeMinutes = recette.duree / 60

Si tu as besoin d'un commentaire pour expliquer ce que fait une ligne, essaie d'abord de renommer la variable ou d'extraire une fonction.

Ranger les fichiers

Un projet qui grandit finit par contenir des dizaines de fichiers. Une structure claire évite de chercher.

Deux approches courantes :

Les petits projets fonctionnent bien par type. Quand une partie du site devient grosse, regrouper par fonctionnalité aide à tout garder au même endroit. Les frameworks imposent souvent une structure : suis-la plutôt que d'en inventer une.

Voici un exemple simple pour le site de recettes :

mon-site/
  index.html
  recettes.html
  css/
    style.css
  js/
    recettes.js
    ingredients.js
  images/

Les noms de fichiers suivent les mêmes règles que les noms dans le code : explicites, sans espaces, sans accents, en minuscules avec des tirets. Un fichier Recette finale (2).html te posera problème tôt ou tard, par exemple dans une adresse web.

À retenir

• Un bon nom dit ce que contient la variable ou ce que fait la fonction.
• Une valeur écrite en dur sans explication est un nombre magique : donne-lui un nom.
• Une fonction fait une seule chose, et son nom la décrit.
• Un commentaire explique le pourquoi, pas le quoi.
• Une structure de dossiers cohérente, avec des noms de fichiers simples, évite de chercher.
• Choisis un style de nommage et garde-le dans tout le projet.