Commenter et documenter son code (PHP)

Objectifs

• Distinguer commentaires (dans le code) et documentation (vue d’ensemble).
• Savoir écrire des DocBlocks PHPDoc simples et utiles.
• Adopter des règles claires et homogènes pour l’équipe.

---

1) Commenter vs documenter

Commenter (dans le code)

But : expliquer l’intention et les choix (le “pourquoi”), pas réécrire le code.

• Placer un commentaire juste au-dessus d’un bloc non évident, d’un calcul “piège”, d’un contournement temporaire.
• Référencer un ticket/bug si besoin (// FIXME: #123).
• Un commentaire faux → à supprimer : mieux pas de commentaire qu’un commentaire trompeur.

À éviter : commenter l’évidence (// ajoute 1 au-dessus de i++) ou écrire des pavés de 20 lignes.

Exemples brefs :

// Règle métier : un panier expire après 30 minutes d'inactivité (SPEC-42).
// On conserve la dernière activité en cache pour éviter une requête DB à chaque hit.

Documenter (vue d’ensemble)

But : aider une personne qui arrive sur le projet à comprendre et utiliser le code.

• README.md : comment lancer, config minimale, structure du projet.
• Guides “How-to” : ex. “ajouter un moyen de paiement”, “configurer l’envoi d’e-mails”.
• Schémas simples (ASCII/Mermaid) si ça évite un long texte.

---

2) PHPDoc minimal et efficace

Pourquoi PHPDoc ? Affiché par l’IDE (autocomplétion, tooltips). Clarifie paramètres, retour, exceptions sans lire l’implémentation.

Règles simples :

• DocBlock au-dessus des classes/méthodes publiques (API) et des propriétés non triviales.
• Description courte (1–2 phrases), factuelle.
• Trois tags de base :
  @param (type, nom, rôle) · @return (type) · @throws (si pertinent).

Exemple (classe + propriété) :

/**
 * Service de paiement (ex. Stripe).
 * Responsable de créer/valider les paiements.
 */
final class PaymentService
{
    /** Client HTTP configuré (timeouts, baseURL). */
    private Client $http;
}

Exemple (méthode) :

/**
 * Calcule le total TTC d'un panier.
 * Hypothèse : TVA unique pour tous les items.
 *
 * @param Cart  $cart    Panier à évaluer.
 * @param float $vatRate Taux de TVA (ex: 0.20).
 * @return float         Total TTC en euros.
 * @throws OverflowException Si le montant dépasse la limite autorisée.
 */
public function totalTtc(Cart $cart, float $vatRate): float { ... }

Exemple (fonction avec tableaux) :

/**
 * Filtre les emails valides (RFC simple).
 *
 * @param string[] $emails Liste d'e-mails.
 * @return string[]        E-mails retenus.
 */
function filterValidEmails(array $emails): array { ... }

Astuce : mettre d’abord les types PHP (hints), puis ajouter PHPDoc là où ça apporte
une info métier (contrat, formats, exceptions).

---

3) Style et cohérence d’équipe

• Noms parlants (verbes pour méthodes, noms métier pour classes/DTO) → moins de commentaires.
• Même structure de DocBlock pour tous : description courte → @param → @return → @throws.
• Tags utiles en plus : @deprecated (avec alternative), @see (lien spec/ticket), @example (mini-usage).
• Nettoyage régulier : supprimer les commentaires obsolètes.

---

4) Atelier rapide

Objectif : ajouter/clarifier les DocBlocks et quelques commentaires d’intention.

1. Choisir une classe avec 2–3 méthodes publiques.
2. Pour chaque méthode : 1–2 phrases “ce que ça fait” + @param + @return + @throws si nécessaire.
3. Ajouter un commentaire d’intention au-dessus d’un bout de code non évident.
4. Vérifier dans l’IDE que les tooltips affichent bien les infos.

Critères de réussite : clair, court, exact ; pas de redite inutile.

---

5) Check-list finale

• [ ] Les noms parlent d’eux-mêmes.
• [ ] Les commentaires expliquent le pourquoi, pas ce que le code montre déjà.
• [ ] Les DocBlocks des méthodes publiques ont bien @param, @return (et @throws si besoin).
• [ ] Aucun commentaire obsolète.
• [ ] Un README minimal existe (lancer le projet, config, structure).

---

6) Pour aller un peu plus loin

• Conventions : PSR-12 (style), PSR-4 (autoload).
• @example dans les DocBlocks pour montrer l’usage attendu d’une API.
• Un petit schéma (ASCII/Mermaid) dans le README quand un flux est non trivial.