PHPDoc et DocBlock : documenter une fonction ou classe PHP

Il existe une étape que beaucoup de développeurs négligent lorsqu’ils débutent avec PHP. Une étape un peu invisible, parfois rébarbative, souvent oubliée, mais terriblement importante pour la suite de leur projet. Cette étape, c’est la documentation interne, et plus précisément la création de DocBlocks conformes à la norme PHPDoc.

• Comprendre comment documenter son code PHP de manière claire pour gagner du temps et éviter les erreurs lors de futures modifications.
• Améliorer la qualité et la lisibilité de son projet grâce à des DocBlocks utiles qui facilitent la collaboration et l’autocomplétion dans les IDE.
• Adopter de bonnes pratiques de documentation qui aident à structurer sa pensée et à écrire un code plus propre et plus professionnel.

Documenter correctement ses fonctions est un cadeau que vous offrez à votre vous du futur. Un merci silencieux que vous recevrez dans six mois, lorsque vous retomberez sur un fichier oublié et que vous lirez une description claire de ce que fait chaque méthode. Documenter vos fonctions PHP, c’est aussi aider les autres développeurs qui croiseront votre code, que ce soit vos collègues, vos élèves, ou une ancienne version de vous fatiguée après trois cafés.

Dans ce guide, je vais vous accompagner pas à pas pour comprendre ce qu’est un DocBlock, à quoi sert PHPDoc et comment utiliser cette approche de documentation dans vos projets PHP, que vous soyez totalement débutant ou déjà à l’aise avec le langage. Nous allons prendre notre temps, décortiquer chaque idée, observer des exemples concrets et vous apprendre à rédiger vos propres blocs de documentation avec naturel et efficacité.

Comprendre ce qu’est un DocBlock

Avant de plonger dans la technique, posons une première pierre : qu’est-ce qu’un DocBlock exactement ?

Un DocBlock est un commentaire particulier placé juste au-dessus d’un élément de votre code (une fonction, une classe, une propriété, voire un fichier entier). Il commence toujours par /** et se termine par */. Ce format n’est pas un hasard : il suit les règles définies par PHPDoc, un standard utilisé depuis des années dans le monde PHP.

Voici un exemple extrêmement simple, juste pour visualiser :

/**
 * Additionne deux nombres et retourne le résultat.
 */
function addition(int $a, int $b): int {
    return $a + $b;
}

À ce stade, ce commentaire a l’air anodin. Pourtant, il peut déjà être compris par des outils automatiques, des éditeurs de code, des IDE comme PHPStorm ou VSCode, et il aide immédiatement à comprendre le rôle de la fonction sans en lire le corps.

Pour qu’un DocBlock soit conforme au standard PHPDoc, il doit respecter une forme particulière, avec des balises commençant par @. Nous découvrirons cela dans la partie suivante, mais retenez pour l’instant qu’un DocBlock est plus qu’une note personnelle. C’est une norme reconnue, comprise par les humains comme par les machines.

Pourquoi un simple commentaire ne suffit pas ?

On pourrait penser qu’une phrase en commentaire standard ferait largement l’affaire :

// Cette fonction additionne deux nombres

C’est vrai… mais seulement pour un humain. Avec un DocBlock, vous faites d’une pierre trois coups :

• Vous documentez pour vous-même.
• Vous documentez pour les autres.
• Vous donnez des informations exploitables à votre éditeur et aux outils automatiques.

Par exemple, un IDE peut comprendre le type de retour, proposer des suggestions de code, générer de la documentation HTML, pointer des erreurs, analyser des types, etc. Un simple commentaire ne permet pas ça. Un DocBlock, oui.

À quoi sert PHPDoc ?

Maintenant que vous voyez ce qu’est un DocBlock, définissons le concept central : PHPDoc.

PHPDoc est une norme. Elle définit la manière correcte de documenter votre code PHP à l’intérieur même de vos fichiers.

On pourrait dire que PHPDoc, c’est le dictionnaire officiel de la documentation PHP. Il explique comment formuler vos commentaires, quelles balises utiliser, dans quel ordre et à quel endroit.

Les objectifs de PHPDoc

PHPDoc sert à trois choses essentielles :

Rendre le code lisible : Lorsque vous relisez votre code plusieurs mois plus tard, vous aurez parfois l’impression de tomber sur un vieux grimoire. PHPDoc vous évite ce moment de solitude en expliquant clairement l’intention de chaque fonction.

Permettre aux IDE de mieux vous assister : Avec un DocBlock bien structuré, votre environnement de développement comprend mieux votre code. Il peut :

• suggérer des méthodes,
• afficher automatiquement les descriptions,
• vérifier les types,
• signaler des incohérences.

C’est un peu comme si vous donniez des lunettes à votre IDE.

Générer une documentation automatique : Certains outils comme phpDocumentor ou Doctum peuvent parcourir vos fichiers, analyser les DocBlocks et produire une documentation complète sous forme de site web. Vous n’avez rien à écrire de plus que vos DocBlocks.

La structure d’un DocBlock : les bases essentielles

Pour les débutants, l’une des questions les plus fréquentes est : “Comment écrire un DocBlock correct ?”. Rassurez-vous, ce n’est pas compliqué. Il suffit de respecter une structure simple, composée de trois zones :

1. Une description courte
2. Une description longue (facultative mais utile)
3. Des balises PHPDoc commençant par @

Regardons cela progressivement.

Exemple d’un DocBlock complet

/**
 * Retourne la somme de deux nombres.
 *
 * Cette fonction accepte deux entiers et renvoie leur addition.
 * Elle sert ici d'exemple simple pour illustrer un DocBlock complet.
 *
 * @param int $a Premier nombre
 * @param int $b Second nombre
 * @return int Résultat de l'addition
 */
function addition(int $a, int $b): int {
    return $a + $b;
}

Décortiquons ce bloc. La première ligne est une description rapide. Elle doit tenir en une phrase simple, claire, sans fioritures.

La deuxième partie permet d’apporter des détails : contexte, logique, usage concret.
Elle reste facultative mais ajoute beaucoup de clarté.

Enfin, viennent les balises. Ce sont elles qui font réellement de votre commentaire un DocBlock conforme à PHPDoc. Elles suivent toujours le format :

@balise type $variable Description

Nous analyserons ces balises en profondeur dans les parties suivantes.

Pourquoi les débutants devraient absolument utiliser PHPDoc ?

Si vous débutez en PHP, vous pourriez penser que documenter vos fonctions est inutile tant que votre code reste simple. C’est une erreur classique, que j’ai moi-même commise lors de mes premiers projets. Je pensais naïvement que la documentation était réservée aux “gros” projets ou aux développeurs seniors. Comme si documenter son code était un niveau bonus qu’on débloquait après des années de pratique.

En réalité, plus vous êtes débutant, plus PHPDoc est votre ami.

Raison 1 : Il vous force à clarifier votre pensée

Lorsque vous devez écrire une description courte d’une fonction, vous devez être capable d’expliquer ce qu’elle fait. Si vous n’arrivez pas à la résumer, c’est souvent que votre fonction fait trop de choses. PHPDoc vous aide donc indirectement à écrire un meilleur code.

Raison 2 : Il renforce votre apprentissage

Décrire vos paramètres, vos types et votre valeur de retour vous fait réfléchir activement à ce que vous codez. Cela améliore votre mémoire et votre compréhension du PHP.

Raison 3 : Les IDE deviennent vos meilleurs alliés

Même VSCode, avec les bonnes extensions, propose une autocomplétion enrichie grâce aux DocBlocks. Vous écrivez mieux, plus vite, en faisant moins d’erreurs.

Lorsque j’ai débuté en PHP, je travaillais sur un petit site vitrine pour un ami. Rien de bien compliqué. J’étais tellement fier de mon code que je n’ai documenté aucune fonction. Six mois plus tard, cet ami me rappelle pour ajouter une fonctionnalité. En ouvrant mes fichiers, j’ai eu l’impression de relire une lettre que je n’avais jamais écrite.

Si j’avais utilisé des DocBlocks, j’aurais gagné deux heures de décryptage…

Les balises PHPDoc indispensables

Dans cette première partie, nous allons aborder les balises essentielles, celles que vous utiliserez dans 95 % des cas. Nous entrerons dans les balises avancées dans la suite de ce guide. Les trois balises fondamentales sont :

• @param
• @return
• @throws

Nous allons déjà explorer les deux premières.

La balise @param

Elle permet d’expliquer les paramètres reçus par une fonction. Elle suit cette structure :

@param type $nom Description

Exemple concret :

/**
 * Calcule la distance entre deux points sur un plan.
 *
 * @param float $x1 Coordonnée X du point 1
 * @param float $y1 Coordonnée Y du point 1
 * @param float $x2 Coordonnée X du point 2
 * @param float $y2 Coordonnée Y du point 2
 * @return float Distance en unités standard
 */
function distance(float $x1, float $y1, float $x2, float $y2): float {
    return sqrt(pow($x2 - $x1, 2) + pow($y2 - $y1, 2));
}

Grâce à ces quatre balises @param, un IDE peut :

• afficher les descriptions automatiquement,
• vérifier que les types correspondent,
• anticiper la valeur attendue,
• faciliter l’autocomplétion.

La balise @return

Elle indique ce que la fonction renvoie. Même si vous utilisez déjà des types de retour (comme : int ou : string), la balise reste extrêmement utile pour préciser le sens du résultat.

Exemple simple :

/**
 * Indique si un nombre est pair.
 *
 * @param int $nombre Nombre à analyser
 * @return bool Retourne true si le nombre est pair
 */
function estPair(int $nombre): bool {
    return $nombre % 2 === 0;
}

Ici, l’IDE sait qu’un booléen est attendu, mais grâce au DocBlock, il peut afficher immédiatement l’explication dans une petite bulle d’information à chaque appel de la fonction.

La balise @throws : documenter les exceptions

Lorsque vous commencez à utiliser les exceptions dans vos projets PHP, il devient essentiel de documenter les erreurs que votre fonction peut lancer. C’est exactement le rôle de la balise @throws.

Cette balise indique à d’autres développeurs — et à vous-même dans quelques mois — qu’un comportement exceptionnel peut survenir, et qu’il faudra le gérer.

Voici un exemple simple mais parlant :

/**
 * Divise un nombre par un autre.
 *
 * @param float $a Numérateur
 * @param float $b Dénominateur, ne doit pas être égal à zéro
 * @return float Résultat de la division
 * @throws InvalidArgumentException Si le dénominateur est égal à zéro
 */
function division(float $a, float $b): float {
    if ($b === 0.0) {
        throw new InvalidArgumentException('Le dénominateur ne peut pas être zéro.');
    }
    return $a / $b;
}

Dans un IDE, l’utilisateur verra immédiatement qu’il doit prévoir un bloc try...catch. C’est une forme de contrat moral : vous annoncez ce que la fonction peut faire, mais aussi ce qu’elle peut provoquer en cas d’erreur.

Une fonction documentée avec @throws inspire confiance, car elle montre que vous avez anticipé l’imprévu et considéré les situations limites.

Les balises supplémentaires essentielles à connaître

PHPDoc ne s’arrête pas à trois balises. Le standard propose en réalité une bibliothèque entière de mots-clés permettant de décrire chaque nuance de votre code. Pour garder ce guide accessible aux débutants, nous allons examiner les balises les plus courantes et les plus utiles dans la majorité des projets.

La balise @var : pour documenter les propriétés

La balise @var permet d’indiquer le type d’une variable, que ce soit une propriété d’objet ou une simple variable dans un fichier. Par exemple, pour une propriété :

class Panier {
    /**
     * @var array Liste des produits ajoutés au panier
     */
    private array $produits = [];
}

Cette balise apporte des informations précieuses à votre IDE, surtout si vous utilisez des tableaux complexes ou des objets imbriqués.

La balise @deprecated : prévenir ce qui ne doit plus être utilisé

Lorsque vous travaillerez sur un projet qui évolue, il vous arrivera de remplacer certaines fonctions. Plutôt que de les supprimer brutalement, vous pouvez les marquer comme inutilisables à l’avenir.

/**
 * @deprecated Utilisez la méthode calculerTotal() à la place.
 */
function totalPanier() {
    // ancienne version
}

Votre éditeur affichera une petite alerte visuelle. Ainsi, les développeurs savent qu’il existe une meilleure méthode.

La balise @see : pour guider vers une ressource liée

Elle permet de créer un lien vers une fonction, une classe ou une documentation externe.

/**
 * Calcule le total TTC.
 *
 * @see calculerTVA()
 */
function calculerTTC() {
    // ...
}

C’est une balise subtile mais efficace pour accroître la compréhension globale.

Écrire la description parfaite dans un DocBlock

Beaucoup de développeurs utilisent des DocBlocks… mais les écrivent mal. Soit ils écrivent peu, soit ils écrivent trop. Une bonne description respecte généralement trois principes :

• Elle est courte.
• Elle explique l’intention.
• Elle est compréhensible sans lire la fonction.

Exemple de mauvaise description

/** Calcul. */

Sans commentaire…

Passons à un exemple de description trop longue :

/**
 * Cette fonction permet de calculer la valeur totale en fonction de différentes informations...
 * puis ensuite elle vérifie chaque paramètre et réalise un ensemble...
 * etc.
 */

On se perd, et le DocBlock perd son utilité.

Voici un exemple correct et équilibré :

/**
 * Calcule le total TTC d’un panier.
 *
 * Cette méthode additionne les prix HT, applique la TVA selon le taux indiqué,
 * puis retourne la valeur finale arrondie.
 */

Le lecteur comprend immédiatement ce que fait la fonction, sans plonger dans sa logique interne.

Documenter une classe complète avec PHPDoc

Jusqu’ici, nous nous sommes concentrés sur la documentation des fonctions PHP. Mais les DocBlocks sont tout aussi utiles pour les classes, les interfaces et les traits.

/**
 * Représente un utilisateur inscrit sur le site.
 *
 * Cette classe gère les informations personnelles,
 * la date d’inscription et les méthodes liées à l’authentification.
 *
 * @author Alban
 * @version 1.0
 */
class Utilisateur {
    /**
     * @var string Nom d'utilisateur
     */
    private string $pseudo;

    /**
     * @var string Adresse email
     */
    private string $email;

    /**
     * @var DateTime Date d'inscription
     */
    private DateTime $inscription;

    /**
     * Crée un nouvel utilisateur.
     *
     * @param string $pseudo Nom d'utilisateur
     * @param string $email Adresse email
     */
    public function __construct(string $pseudo, string $email) {
        $this->pseudo = $pseudo;
        $this->email = $email;
        $this->inscription = new DateTime();
    }
}

Vous voyez qu’une classe complète peut être documentée de manière précise, structurée et surtout lisible.

• Chaque propriété est explicitement décrite.
• Chaque méthode possède un rôle clair.
• L’utilisateur du code comprend votre intention.

Pour les débutants, consultez notre Tutoriel complet sur la POO en PHP et les classes et méthodes.

Comment PHPDoc améliore votre IDE

Pour vous montrer à quel point PHPDoc améliore réellement votre productivité, imaginons que vous travailliez dans un éditeur comme VSCode ou PHPStorm. Vous commencez à taper le nom de votre fonction pour l’appeler :

calculerTTC(

Votre IDE affiche automatiquement :

calculerTTC()
Calcule le total TTC d’un panier.
Retourne la valeur TTC arrondie.
@param float $prixHT
@param float $tauxTVA
@return float

Et tout cela grâce à votre DocBlock.

Ce confort n’a l’air de rien, mais lorsqu’on travaille sur un projet de plusieurs dizaines de fonctions, c’est un gain énorme en rapidité et en clarté. Vous ne perdez plus de temps à rouvrir chaque fichier pour comprendre ce que fait une fonction.

Votre code devient auto-expliqué.

Documenter le comportement, pas seulement les types

Une erreur fréquente chez les débutants consiste à se contenter de décrire les types dans un DocBlock. Or, PHPDoc ne sert pas à remplir une fiche technique, mais à expliquer le sens de votre fonction. Regardez ces deux versions :

Version pauvre :

/**
 * @param int $a
 * @param int $b
 * @return int
 */

On est d’accord : on ne sait rien. Voici donc la version utile, la bonne version :

/**
 * Additionne deux entiers et retourne leur somme.
 *
 * @param int $a Premier nombre
 * @param int $b Second nombre
 * @return int Résultat de l'addition
 */

Dans la vie réelle, les développeurs préfèrent largement cette version. Elle est claire, pédagogique, utile et parfaitement conforme aux bonnes pratiques PHPDoc.

Quand un DocBlock est-il inutile ?

Même si PHPDoc est très pratique, il ne faut pas tomber dans l’excès inverse et documenter des évidences. Par exemple, une méthode évidente comme :

public function getNom(): string {
    return $this->nom;
}

Peut être documentée, mais ce n’est pas obligatoire.

Si la méthode est triviale, et que le type retourné est clair, un DocBlock n’ajoute pas réellement de valeur. Certains frameworks comme Symfony encouragent même à ne pas documenter les getters et setters trop simples.

Le but n’est pas d’écrire pour écrire, mais d’aider réellement.

Générer automatiquement vos DocBlocks

Bonne nouvelle : vous n’êtes pas obligé de taper un DocBlock entièrement à la main. La majorité des IDE peut générer automatiquement un DocBlock simplement en écrivant /** puis en appuyant sur Entrée.

L’éditeur génère :

/**
 * Summary of functionName
 *
 * @param type $param
 * @return type
 */

Ensuite, il ne vous reste qu’à remplir les trous. L’automatisation ne remplace pas l’humain, mais elle fait gagner beaucoup de temps, surtout sur les méthodes longues.

C’est souvent à ce moment que les débutants prennent goût à la documentation. Quand on se rend compte qu’il suffit de quelques secondes pour écrire un bon DocBlock, on commence à en mettre partout, presque naturellement.

Les erreurs fréquentes à éviter avec PHPDoc

Lorsque l’on débute avec les DocBlocks, certaines erreurs reviennent très souvent. Elles ne sont pas graves en soi, mais elles diminuent l’utilité réelle de votre documentation. Comme j’ai moi-même commis chacune de ces erreurs au moins une fois, autant vous éviter quelques détours.

1. Ne pas mettre à jour les DocBlocks

C’est probablement la faute la plus répandue. Vous écrivez un DocBlock propre, complet, puis vous modifiez la fonction… mais vous oubliez de corriger la documentation. Résultat : le DocBlock ment.

Une méthode censée “calculer un prix TTC” pourrait désormais “calculer un prix HT”, et personne ne le saurait. Un DocBlock obsolète est pire qu’un DocBlock absent, car il trompe le lecteur.

2. Décrire l’évidence

Un DocBlock trop basique ou redondant avec le nom de la fonction n’apporte aucune valeur. Par exemple :

/**
 * Récupère le nom.
 *
 * @return string
 */
function getNom(): string {}

Ici, la description ne sert à rien. Documenter doit rester utile, pas systématique.

3. Ignorer les types complexes

Certaines fonctions renvoient des structures plus subtiles qu’un simple int ou string : Tableaux, objets, collections, résultats hybrides… Une erreur fréquente consiste à simplifier abusivement le type :

@return array

Alors qu’une description plus précise est bien plus informative :

@return array<string, float> Prix classés par produit

Les génériques ne sont pas strictement obligatoires, mais ils aident énormément à la compréhension.

4. Rédiger comme un robot

Certains DocBlocks donnent l’impression d’avoir été générés automatiquement par un script sans âme. Une bonne documentation est claire, humaine, bien formulée. Ne tombez pas dans les descriptions télégraphiques comme :

Adds items.

Une phrase, un verbe, un objectif précis : c’est la clé.

Documenter un fichier PHP entier

Les DocBlocks ne sont pas réservés aux fonctions et aux classes. Il existe un type particulier de DocBlock appelé File-level DocBlock. Il se place tout en haut du fichier, juste avant le <?php.

Pour aller plus loin, découvrez L’ensemble des balises d’ouverture et fermeture en PHP.

Ce type de DocBlock est utile pour donner une vision d’ensemble de ce que contient le fichier, notamment dans les projets structurant beaucoup de classes.

<?php
/**
 * Fichier de gestion des commandes.
 *
 * Ce fichier contient les classes et fonctions utiles pour créer,
 * valider, expédier et archiver les commandes du site.
 *
 * @package App\Commandes
 */

Ce DocBlock n’est pas obligatoire, mais il devient précieux dans des projets où plusieurs dizaines de fichiers peuvent avoir des fonctions similaires ou complémentaires.

Les tags avancés de PHPDoc

Nous avons vu les balises fondamentales, mais il existe une multitude d’autres tags qui peuvent vous rendre service lorsque votre code devient plus ambitieux. Voici les plus utiles à connaître sans entrer dans la complexité excessive.

La balise @example

Elle permet de montrer comment utiliser une fonction directement dans le DocBlock.

Des formations informatique pour tous !

Débutant ou curieux ? Apprenez le développement web, le référencement, le webmarketing, la bureautique, à maîtriser vos appareils Apple et bien plus encore…

Formateur indépendant, professionnel du web depuis 2006, je vous accompagne pas à pas et en cours particulier, que vous soyez débutant ou que vous souhaitiez progresser. En visio, à votre rythme, et toujours avec pédagogie.

Découvrez mes formations Qui suis-je ?

/**
 * Formate un prix en euros.
 *
 * @example formatterPrix(12.5) Retourne "12,50 €"
 */

Cette balise est particulièrement utile pour la documentation générée automatiquement.

La balise @inheritdoc

Elle indique que la documentation provient d’une classe ou méthode parente.

/**
 * @inheritdoc
 */
public function calculer() { ... }

Elle évite la duplication dans les héritages complexes.

La balise @uses / @used-by

Elle permet de montrer les dépendances entre fonctions.

/**
 * @uses genererPDF()
 */
function envoyerFacture() { ... }

Ces tags sont des pépites pour comprendre le fonctionnement global d’un module.

Générer automatiquement une documentation HTML avec phpDocumentor

L’une des grandes forces du système PHPDoc, c’est qu’il peut servir de base pour produire une documentation complète sous forme de site web. Un peu comme ce que vous pouvez voir dans la documentation officielle de Symfony ou Doctrine.

L’outil historique, le plus connu et le plus simple à prendre en main, est phpDocumentor. Voici comment cela fonctionne dans la pratique :

Étape 1 : Installer l’outil

Vous pouvez installer phpDocumentor via Composer :

composer require --dev phpdocumentor/phpdocumentor

Étape 2 : Lancer la génération

En ligne de commande :

vendor/bin/phpdoc

A cet instant, phpDocumentor lit votre projet, explore vos fichiers PHP, analyse chaque DocBlock, puis génère un site complet (HTML, CSS, pages détaillées…). Ce site contient la documentation de vos classes, fonctions, namespaces, propriétés, exceptions, relations, et plus encore.

Étape 3 : Lire votre documentation

Vous obtenez un dossier output/ que vous pouvez ouvrir dans un navigateur ou mettre en ligne. C’est une étape souvent impressionnante pour un débutant.

On réalise soudain que de simples DocBlocks, écrits à la main, permettent de créer une véritable documentation technique professionnelle.

Pourquoi PHPDoc améliore la qualité de votre code sur le long terme

Lorsque vous prenez l’habitude de documenter vos fonctions avec des DocBlocks, vous remarquez très vite un changement subtil dans votre manière de programmer.

• Vous réfléchissez davantage avant d’écrire une fonction.
• Vous vous demandez si les paramètres sont cohérents.
• Vous évitez les fonctions trop longues, car elles seraient difficiles à documenter.

Documenter ses fonctions, ce n’est pas un simple ajout esthétique : c’est un processus qui améliore la structure même de votre code. C’est un cercle vertueux :

Code clair → DocBlock clair → Architecture claire.

On pourrait presque dire que PHPDoc agit comme un coach invisible qui vous guide vers des choix plus propres.

Dans un ancien projet, l’un de mes collègues avait développé un système de calcul des remises commerciales. Le code était complexe, rempli de conditions selon le type de client, les montants cumulés, les offres en cours… Bref, un véritable labyrinthe.

Ce collègue avait eu la présence d’esprit de documenter chaque fonction avec des DocBlocks détaillés, y compris des exemples d’utilisation, des descriptions de comportements particuliers et des explications sur les exceptions.

Un jour, il a dû partir en urgence pendant une semaine, au beau milieu d’une phase critique du projet. Sans ses DocBlocks, personne ne serait venu à bout de son module. Mais grâce à sa documentation claire, nous avons pu reprendre le code sans stresser, comprendre sa logique, corriger un bug et intégrer une fonctionnalité supplémentaire.

C’est ce jour-là que j’ai compris que documenter, ce n’est pas pour les autres… c’est pour l’équipe entière, y compris vous-même.

Les bonnes pratiques incontournables pour vos DocBlocks

Même si PHPDoc laisse une certaine liberté, quelques règles pratiques permettent de garder une documentation propre, précise et durable.

1. Toujours synchroniser le code et la documentation

Une modification = une mise à jour du DocBlock. Faites-en un réflexe automatique.

2. Décrire le comportement, pas l’implémentation

Votre fonction peut changer de logique interne sans que son rôle change. Votre DocBlock doit expliquer l’intention, pas les détails techniques.

3. Privilégier la clarté à la sophistication

Mieux vaut une phrase simple que trois lignes complexes.

4. Mettre en avant les types réels

Si vous retournez un tableau structuré, décrivez son contenu. Si vous utilisez une classe comme retour, précisez son rôle.

5. Uniformiser votre style

Choisissez un style d’écriture et tenez-vous-y. Vos DocBlocks seront harmonieux et plus agréables à lire.

Intégrer PHPDoc dans un workflow professionnel

Dans de nombreux projets professionnels, la documentation n’est pas un acte isolé. Elle fait partie d’un ensemble plus large de bonnes pratiques de développement. Pour que PHPDoc s’intègre correctement dans un workflow, il faut comprendre que la documentation doit évoluer en même temps que le code.

Dans les équipes expérimentées, on suit souvent une règle simple : si une fonction change, son DocBlock doit changer dans la même Pull Request.

Consultez notre Guide pour bien utiliser Git.

C’est une façon d’éviter les décalages et de garantir que le code présenté à la relecture est compréhensible et cohérent. Cela semble évident, mais c’est une discipline importante lorsque plusieurs développeurs travaillent ensemble.

La revue de code et les DocBlocks

Lors des revues de code (code reviews), les DocBlocks font partie des éléments contrôlés. On ne se contente pas de vérifier que le code fonctionne : on vérifie également s’il est lisible, cohérent et bien documenté.

Il arrive même parfois que les relecteurs demandent de réécrire une description pour qu’elle soit plus claire. Un DocBlock est une partie du code, pas un supplément facultatif. C’est ce qui permet à toute l’équipe de comprendre et maintenir facilement un projet.

Utiliser PHPDoc avec des outils d’analyse statique

Les DocBlocks jouent un rôle essentiel avec les outils d’analyse statique comme PHPStan ou Psalm. Ces outils vérifient la cohérence des types, détectent des erreurs de logique et préviennent les bugs avant même que votre code ne soit exécuté.

Voici ce qui se passe lorsque vous combinez DocBlocks et analyse statique :

• Votre code devient plus fiable.
• Les erreurs de type sont détectées tôt.
• Vous gagnez du temps sur le debugging.
• Vous améliorez la robustesse générale du projet.

Prenons un exemple concret : si vous documentez qu’un paramètre doit être un tableau de chaînes de caractères, mais qu’une autre partie du code y insère des nombres, PHPStan vous avertira immédiatement.

Ainsi, PHPDoc n’est pas qu’une aide à la lecture : c’est aussi un outil de prévention des bugs.

Enseigner PHPDoc aux débutants : une approche efficace

Si vous êtes amené à transmettre vos connaissances, par exemple à vos élèves, vos collègues juniors ou des débutants que vous accompagnez, il existe une approche douce et progressive pour introduire la pratique des DocBlocks.

Commencer par les descriptions simples

Ne pas entrer immédiatement dans les balises complexes. Le plus important est de faire comprendre que chaque fonction doit avoir une intention claire.

Introduire progressivement les balises essentielles

Une fois la description maîtrisée, on ajoute @param et @return.
C’est largement suffisant pour débuter.

Expliquer que PHPDoc aide à réfléchir

Souvent, les débutants voient la documentation comme une tâche “à côté” du code. Expliquez-leur que rédiger un DocBlock les oblige à clarifier leur fonction. S’ils n’arrivent pas à résumer leur code en une phrase, c’est généralement que la fonction fait trop de choses.

Montrer les effets dans un IDE

C’est souvent le déclic. Dès qu’ils voient apparaître les descriptions automatiquement dans VSCode ou PHPStorm, ils comprennent l’intérêt pratique.

DocBlock et programmation orientée objet : aller plus loin

Dans les projets orientés objet, PHPDoc prend encore plus d’importance parce qu’il structure vos classes, vos méthodes, vos propriétés et vos relations internes.

Documenter les propriétés complexes

Les propriétés qui contiennent plusieurs types possibles peuvent être décrites clairement :

/**
 * @var Produit[] Liste des produits présents dans la commande
 */
private array $produits;

Ici, on comprend immédiatement que le tableau contient des instances de la classe Produit.

Documenter les interfaces et les classes abstraites

C’est particulièrement important pour les développeurs qui devront créer des classes qui étendent les vôtres.

/**
 * Interface définissant un moyen de paiement.
 *
 * Toute classe implémentant cette interface doit fournir une méthode
 * pour valider le paiement et une autre pour annuler l'opération.
 */
interface PaiementInterface { ... }

Grâce à ce DocBlock, les développeurs savent comment structurer leurs classes sans lire chaque détail.

Les différences entre documentation interne et documentation externe

Même si PHPDoc permet de générer une documentation complète, il ne remplace pas la documentation externe destinée aux utilisateurs finaux ou aux clients.

Documentation interne : Comprend les DocBlocks, les commentaires et tout ce qui reste dans le code. Son objectif est d’aider les développeurs à comprendre comment fonctionne le projet.

Documentation externe : Se présente sous forme de pages web, PDF, tutoriels, etc. Elle explique comment utiliser l’application, l’API, la bibliothèque ou le module.

PHPDoc est un outil idéal pour automatiser la documentation interne. Il peut contribuer à la documentation externe, mais ce n’est pas sa vocation première.

Les alternatives à PHPDoc : que faut-il savoir ?

Même si PHPDoc est la norme la plus utilisée dans l’écosystème PHP, il est intéressant de connaître quelques alternatives ou variantes. Cela vous permet de comprendre les différences et de choisir un format adapté si votre contexte change.

DocBlocks de style JSDoc

Certains développeurs ayant travaillé en JavaScript sont habitués au style JSDoc. PHPDoc reprend beaucoup de conventions similaires, mais pas toutes. Il vaut mieux rester conforme au standard PHPDoc pour éviter les confusions.

Attributs PHP (depuis PHP 8)

PHP 8 introduit les attributes, une nouvelle manière d’annoter les classes et méthodes. Par exemple :

#[Route('/profil')]

Ces attributs ne remplacent pas PHPDoc, car ils ne documentent pas. Ils servent davantage à configurer des comportements. On peut toutefois utiliser les deux en parallèle.

Découvrez la liste des nouveautés avec PHP 8.5.

Outils internes ou conventions maison

Certaines équipes créent leurs propres standards, mais c’est rarement utile. PHPDoc est largement reconnu, supporté, uniformisé et compatible avec les outils modernes. Aujourd’hui, utiliser autre chose est souvent un handicap.

DocBlocks et legacy code : comment documenter un vieux projet ?

Documenter un projet déjà existant, parfois ancien et complexe, peut sembler décourageant. Pourtant, PHPDoc peut devenir un excellent allié pour faire revivre un code que l’on croyait oublié.

Voici une stratégie efficace :

1. Commencer par les fonctions les plus utilisées : Il n’est pas nécessaire de documenter tout un projet d’un coup. Commencez par les fonctions centrales : celles qui sont appelées partout.

2. Documenter au fur et à mesure : À chaque fois que vous ouvrez un fichier pour corriger un bug ou ajouter une fonctionnalité, profitez-en pour documenter ce que vous voyez.

3. Utiliser des outils d’analyse : PHPStan et Psalm détectent les types manquants ou incohérents. Cela vous aide à comprendre le comportement réel du code.

4. Éviter la documentation massive sans réflexion : Le but n’est pas de remplir tous les fichiers de commentaires, mais d’améliorer progressivement la compréhension du projet. C’est une approche pragmatique et durable.

L’impact de PHPDoc sur la lisibilité globale du projet

Lorsque vous travaillez sur un projet bien documenté, quelque chose change dans votre manière d’appréhender le code.

• Les fichiers semblent plus clairs.
• Les fonctions racontent une histoire.
• Les modules communiquent entre eux.

Un bon DocBlock agit comme une pancarte sur un chemin de randonnée : il vous indique où vous êtes, vers où vous allez, et ce que vous allez trouver.
Même si vous n’empruntez pas ce chemin tous les jours, ces balises rendent votre progression plus agréable et moins risquée.

Lorsque l’on découvre PHPDoc et les DocBlocks, on peut les considérer comme une tâche annexe, presque facultative. Pourtant, ils représentent bien plus que cela. Ce sont des outils puissants, subtils et profondément utiles qui transforment non seulement votre code, mais aussi votre manière de réfléchir.

PHPDoc n’est pas là pour remplir vos fichiers de texte inutile. Il est là pour vous accompagner, éclaircir votre logique, guider votre équipe et renforcer la fiabilité globale de vos projets. Un bon DocBlock n’est pas un simple commentaire : c’est une promesse de clarté, une trace de votre intention, un guide pour le développeur qui reprendra votre travail un jour… et souvent, ce développeur, c’est vous-même.

Documenter son code, c’est un geste humble, presque invisible, mais qui témoigne d’une grande maturité professionnelle. Cela demande de la régularité, un peu d’exigence et beaucoup de bienveillance envers vos collègues et envers votre futur vous. Vous verrez qu’à mesure que vos projets grandiront, documenter vos fonctions deviendra un réflexe naturel, presque logique. Et c’est peut-être là la plus belle force de PHPDoc : il ne vous demande rien d’extraordinaire, juste d’expliquer ce que vous faites avec simplicité et sincérité.

Foire aux questions (FAQ) sur PHPDoc et les DocBlocks

Pour terminer ce guide, il est utile de répondre aux questions qui reviennent le plus souvent lorsque l’on commence à utiliser PHPDoc. Cette section permettra à vos lecteurs de lever les derniers doutes avant de se lancer.

“Faut-il vraiment documenter toutes les fonctions ?”

La réponse est non.
Documenter intelligemment, ce n’est pas documenter systématiquement. Certaines méthodes évidentes, comme les getters et setters basiques, peuvent être parfaitement compréhensibles sans DocBlock.

Mais pour toutes les méthodes qui contiennent une logique métier, manipulent des données ou risquent de prêter à confusion… oui, il est préférable d’ajouter un DocBlock clair et précis.

“Les types dans PHP ne suffisent-ils pas ?”

Les types sont indispensables, mais ils ne remplacent pas la documentation. Le type int vous indique la nature de la donnée, mais il ne vous raconte pas son intention.

Par exemple :

@return int

Cela ne dit pas si l’entier représente une quantité, un prix, une durée, une position dans un tableau, un identifiant… PHPDoc permet de lever cette ambiguïté.

“Les DocBlocks sont-ils lus par les serveurs ? Alourdissent-ils le code ?”

Non.
Le serveur PHP ignore totalement les commentaires. Ils n’ont aucun impact sur la performance de votre application, même sur un serveur très sollicité. Ils sont faits pour les humains, et pour les outils d’analyse — pas pour le moteur PHP lui-même.

“Existe-t-il des extensions VSCode pour PHPDoc ?”

Oui, plusieurs extensions facilitent l’écriture automatique de DocBlocks. L’une des plus populaires est PHP Intelephense, qui autocomplète les types, génère des DocBlocks et signale les incohérences.

Une autre extension très utile est PHP DocBlocker, qui génère automatiquement la structure du DocBlock dès que vous tapez /** puis Entrée.

“Dois-je préférer les attributs PHP aux DocBlocks depuis PHP 8 ?”

Les attributs PHP ne remplacent pas PHPDoc. Ils permettent de configurer des comportements internes (comme des routes, des contraintes, des règles), mais ne servent pas à documenter. PHPDoc reste la solution officielle pour la documentation du code.

Étude de cas complète : comment documenter un mini-module PHP

Pour aller plus loin, imaginons un petit module très simple : un service qui gère des messages. Voici comment on pourrait documenter correctement l’ensemble du code afin que même un développeur débutant puisse comprendre son fonctionnement du premier coup d’œil.

Le fichier principal

<?php
/**
 * Gestionnaire de messages pour le site.
 *
 * Ce module permet de créer, valider et afficher des messages,
 * par exemple dans un espace de contact ou un module de support client.
 *
 * @package App\Service\Messages
 */

La classe Message

/**
 * Représente un message envoyé par un utilisateur.
 *
 * Cette classe contient le contenu, la date d'envoi,
 * ainsi que l'adresse email de l'expéditeur.
 */
class Message
{
    /**
     * @var string Contenu du message
     */
    private string $contenu;

    /**
     * @var string Adresse email de l'expéditeur
     */
    private string $email;

    /**
     * @var DateTime Date d'envoi du message
     */
    private DateTime $date;

    /**
     * Crée un nouveau message.
     *
     * @param string $contenu Contenu du message
     * @param string $email Adresse email de l'expéditeur
     * @throws InvalidArgumentException Si les données sont vides ou invalides
     */
    public function __construct(string $contenu, string $email)
    {
        if (empty($contenu) || empty($email)) {
            throw new InvalidArgumentException("Le contenu et l'email sont obligatoires.");
        }

        $this->contenu = $contenu;
        $this->email = $email;
        $this->date = new DateTime();
    }

    /**
     * Retourne le contenu du message.
     *
     * @return string Contenu du message
     */
    public function getContenu(): string
    {
        return $this->contenu;
    }
}

Le service MessageService

/**
 * Service permettant de gérer une liste de messages.
 *
 * Cette classe fournit des méthodes pour ajouter un message,
 * valider son contenu et récupérer la liste complète.
 */
class MessageService
{
    /**
     * @var Message[] Liste des messages
     */
    private array $messages = [];

    /**
     * Ajoute un message à la liste après validation.
     *
     * @param Message $message Message à ajouter
     * @return bool Retourne true si le message a été ajouté
     */
    public function ajouter(Message $message): bool
    {
        $this->messages[] = $message;
        return true;
    }

    /**
     * Retourne la liste des messages stockés.
     *
     * @return Message[] Liste complète des messages
     */
    public function getMessages(): array
    {
        return $this->messages;
    }
}

Dans cet exemple, chaque classe est documentée, chaque fonction est expliquée, chaque variable est claire. Même un développeur débutant peut comprendre l’ensemble du module sans effort.

C’est exactement cela, la force de PHPDoc et des DocBlocks.

Le lien entre PHPDoc et l’éducation au code

On sous-estime souvent le rôle pédagogique de PHPDoc. Lorsque vous enseignez la programmation à un débutant, l’une des difficultés majeures est de l’aider à structurer sa pensée. Souvent, les débutants écrivent des fonctions de 30 lignes sans réfléchir au rôle de chacune.

Avec PHPDoc, tout change.

Dès que vous imposez d’écrire une description courte, vous posez la question :

“Qu’est-ce que cette fonction doit faire ?”

Pour beaucoup, c’est une révélation. Cela clarifie l’intention, élimine les confusions et encourage une logique plus propre. Documenter devient un exercice mental qui renforce la capacité à écrire du code maintenable.

En ce sens, PHPDoc n’est pas seulement un outil technique. C’est un outil pédagogique qui accompagne la maturation du développeur.

L’avenir de PHPDoc : pourquoi cette norme reste essentielle

Dans un monde où les langages évoluent vite, on pourrait se demander si PHPDoc sera toujours utilisé dans cinq ou dix ans. La réponse est très probablement oui, pour plusieurs raisons simples :

• Les commentaires resteront toujours nécessaires.
• Les IDE continueront d’exploiter PHPDoc pour enrichir l’autocomplétion.
• Les analyses statiques gagnent en popularité et reposent fortement sur les DocBlocks.
• Le code doit rester lisible, quel que soit l’avancement des technologies.

Même si les attributs PHP et d’autres innovations continuent d’apparaître, rien ne remplace la simplicité, l’efficacité et la lisibilité d’un DocBlock clair.

La norme PHPDoc accompagne les développeurs depuis plus de vingt ans.
Et elle continuera probablement encore longtemps.

PHPDoc, un outil qui dépasse la documentation

Si vous êtes arrivé jusqu’ici, vous avez déjà compris que PHPDoc et les DocBlocks ne sont pas de simples accessoires décoratifs. Ce sont des partenaires, des alliés, presque des mentors silencieux dans votre pratique quotidienne de PHP.

Documenter une fonction avec soin, c’est comme envoyer un message dans le futur. Vous faites un cadeau à la version future de vous-même, ou à la personne qui prendra votre place un jour. C’est aussi une preuve de professionnalisme, d’attention et de respect envers ceux qui liront votre code.

Bien utiliser PHPDoc, ce n’est pas écrire plus.

• C’est écrire mieux.
• C’est clarifier vos intentions, structurer votre architecture, transmettre vos idées.

Et lorsque vos projets grandiront, vous réaliserez à quel point ces petits blocs de texte vous auront simplifié la vie.

Continuez à écrire, à documenter, à expliquer. Votre code vous remerciera. Vos collègues aussi. Et votre vous du futur encore davantage !

Alban

Fondateur de l’agence Créa-troyes.
Intervenant en Freelance.
Contactez-moi

crea-troyes.fr