06/02 - Clean code - Documentation du développeur

1. Le Nommage : Soyez Expressifs

Le nom d’une variable ou d’une fonction doit dire pourquoi elle existe, ce qu’elle fait et comment on l’utilise. ❌ Mauvais (Peu clair)

// On ne sait pas ce que sont 'p', 'l' ou 'v'
$p = 150;
$l = array_reduce($items, fn($a, $i) => $a + $i->price, 0);

if ($l > $p) {
    $v = $l * 0.1;
    $t = $l - $v;
    echo $t;
}

✅ Bon (Explicite)

const MINIMUM_ORDER_FOR_DISCOUNT = 150;
const DISCOUNT_RATE_PERCENTAGE = 0.1; // 10%

$orderTotal = array_reduce($cartItems, fn($total, $item) => $total + $item->price, 0);

if ($orderTotal > MINIMUM_ORDER_FOR_DISCOUNT) {
    $discountAmount = $orderTotal * DISCOUNT_RATE_PERCENTAGE;
    $finalPriceWithDiscount = $orderTotal - $discountAmount;
    
    echo $finalPriceWithDiscount;
}

2. Les Fonctions : Faites une seule chose (SRP)

Une fonction (ou un service) doit avoir une seule responsabilité. Si tu as besoin du mot “et” pour décrire ce que fait ta fonction, c’est qu’elle doit être découpée. ❌ Mauvais (Symfony - Service “fourre-tout”)

// Un service qui fait trop de choses
public function handleUserSignup(array $data): User
{
    // 1. Logique de validation métier
    if (strlen($data['password']) < 8) {
        throw new \Exception("Trop court");
    }

    // 2. Persistance (Base de données)
    $user = new User($data);
    $this->entityManager->persist($user);
    $this->entityManager->flush();

    // 3. Logique de communication (Email)
    $email = (new Email())
        ->to($user->getEmail())
        ->subject('Bienvenue !')
        ->text("Bienvenue " . $user->getFirstName());
    $this->mailer->send($email);

    // 4. Logique de marketing (Tracker)
    $this->analytics->track('user_created', ['id' => $user->getId()]);

    return $user;
}

✅ Bon (Responsabilités séparées) Le Service Principal (Responsabilité : Créer) Il ne sait pas qu’un mail doit être envoyé, il dit juste : “J’ai fini mon travail”.

public function createUser(UserDto $data): User
{
    $user = $this->userRepository->save($data);

    // On émet un événement. C'est tout.
    $this->eventDispatcher->dispatch(new UserCreatedEvent($user));

    return $user;
}

Le Listener d’Email (Responsabilité : Communiquer) Ce code vit dans un autre fichier. Il ne s’occupe que de la mise en forme et de l’envoi.

#[AsEventListener(event: UserCreatedEvent::class)]
public function onUserCreated(UserCreatedEvent $event): void
{
    $user = $event->getUser();
    $welcomeMessage = $this->templateService->buildWelcome($user->getName());
    $this->emailService->send($user->getEmail(), "Bienvenue", $welcomeMessage);
}

Le Listener Analytics (Responsabilité : Analyser) Si demain on veut arrêter de tracker les utilisateurs, on supprime juste ce bloc, sans toucher au code de création d’utilisateur.

#[AsEventListener(event: UserCreatedEvent::class)]
public function logUserAnalytics(UserCreatedEvent $event): void
{
    $this->analytics->track('new_registration', ['userId' => $event->getUser()->getId()]);
}

3. Le Principe de “Don’t Repeat Yourself” (DRY)

Évite de copier-coller. Si tu vois la même logique deux fois, centralise-la. ❌ Mauvais (Twig/PHP - Duplication)

<div style="padding: 10px; border: 1px solid black;">Profil Utilisateur</div>

<div style="padding: 10px; border: 1px solid black;">Profil Admin</div>

✅ Bon (Composant/Inclusion réutilisable)

<div class="card-styles">{{ content }}</div>

{% include '_card.html.twig' with {'content': 'Profil Utilisateur'} %}

4. Les Commentaires : Le code doit s’expliquer seul

N’utilise les commentaires que pour expliquer le “Pourquoi” (décisions complexes), jamais le “Quoi”. Si le code est complexe, renomme tes variables. ❌ Mauvais

// Vérifie si l'utilisateur est actif et a plus de 18 ans
if ($u->getStatus() === 'active' && $u->getAge() > 18) { ... }

✅ Bon

$isEligibleAdult = $user->isActive() && $user->isAdult();
if ($isEligibleAdult) { ... }

5. Les Principes SOLID (Le “S” et le “O”)

Principe	Définition simple
Single Responsibility	Un fichier = Une mission.
Open/Closed	Ton code doit être ouvert à l’extension mais fermé à la modification.

S : Single Responsibility Principle (SRP)

“Une classe ou une fonction ne devrait avoir qu’une seule raison de changer.” Si ton fichier s’occupe à la fois de calculer un prix, de formater une date et d’envoyer une notification, il a trop de raisons de changer. ❌ Le mauvais élève (La classe “Dieu”)

class Invoice {
    public function calculateTotal(array $items) { /* ... */ }
    public function generateHTML() { /* ... */ } // ❌ Affichage
    public function saveToDatabase() { /* ... */ } // ❌ Persistance
}

✅ Le bon élève (Découpage)

InvoiceCalculator : Ne connaît que les chiffres.
InvoiceRenderer : Ne connaît que le HTML/PDF (Twig).
InvoiceRepository : Ne connaît que la base de données (Doctrine).

O : Open/Closed Principle (OCP)

“Ouvert à l’extension, fermé à la modification.” Tu devrais pouvoir ajouter une nouvelle fonctionnalité sans modifier le code existant. ❌ Mauvais : Le switch infini

// Si on veut ajouter "Espagne", on DOIT modifier cette fonction
function getShippingCost(string $country): int {
    if ($country === 'France') return 5;
    if ($country === 'Belgium') return 7;
    if ($country === 'USA') return 15;
    // ... Début de l'enfer
}

✅ Bon : L’approche par polymorphisme

// 1. On définit une règle générale
interface ShippingStrategy {
    public function calculate(): int;
}

// 2. On crée des extensions pour chaque cas
class FranceShipping implements ShippingStrategy {
    public function calculate(): int { return 5; }
}

class USAShipping implements ShippingStrategy {
    public function calculate(): int { return 15; }
}

// 3. Le code principal est "fermé" : il ne change jamais.
function displayCost(ShippingStrategy $strategy) {
    echo $strategy->calculate();
}

6. Structure et Clean Architecture (Symfony)

En Symfony, respectez la hiérarchie pour ne pas transformer les contrôleurs en usines à gaz. Règle d’or :

Controller : Reçoit la Request, valide les données (Form ou MapRequestPayload), renvoie la Response. Pas de logique métier.
Service : Contient toute la logique métier.
Repository/Entity : Gère l’accès aux données via Doctrine.

Exemple de structure propre :

src/
└── User/
    ├── Controller/       # Contrôleurs Web/API
    ├── Dto/              # Objets de transfert de données
    ├── Entity/           # Entités Doctrine
    ├── EventListener/    # Gestion des événements
    ├── Repository/       # Requêtes SQL (QueryBuilder)
    └── Service/          # Logique métier pure

Résumé pour l’équipe

Lisibilité > Brièveté : On s’en fiche que le code soit court, on veut qu’il soit clair.
Petit, c’est mieux : Des méthodes de moins de 20 lignes, des classes spécialisées.
Supprime le code mort : Si une fonction n’est plus utilisée, on l’efface (Git s’en souvient).

​1. Le Nommage : Soyez Expressifs

​2. Les Fonctions : Faites une seule chose (SRP)

​3. Le Principe de “Don’t Repeat Yourself” (DRY)

​4. Les Commentaires : Le code doit s’expliquer seul

​5. Les Principes SOLID (Le “S” et le “O”)

​S : Single Responsibility Principle (SRP)

​O : Open/Closed Principle (OCP)

​6. Structure et Clean Architecture (Symfony)

​Résumé pour l’équipe