Commentaires PHP : Guide pratique pour bien commenter son code

Écrit par:

ultime

Développeur Fullstack depuis 2017

Les commentaires sont des alliés précieux dans tous langage de programmation comme PHP. Ils permettent de documenter les classes, mes méthodes, les fonctions et d’expliquer les intentions derrière vos choix techniques et de faciliter la maintenance future de vos applications web. Que vous soyez débutants ou développeurs expérimentés, savoir commenter intelligemment votre code-source PHP fait toute la différence dans développement web professionnel. Voici tout ce qu’il faut savoir sur les commentaires PHP.

Table des matières

Quels sont les différents types de commentaires en PHP ?

PHP propose trois types de commentaires principaux à utiliser dans vos pages web,librairies, bibliothèques de code,scripts et templates, chacun avec ses cas d’usage spécifiques. Voici comment les utiliser avec des exemples concrets.

1. Les commentaires sur une seule ligne

Le commentaire sur une ligne utilise // ou #. Utiliser pour annoter rapidement une logique ou désactiver une ligne temporairement. Simple et rapide pour les explications courtes à côté d’une instruction.

<?php
// Calcul du prix total avec TVA 20%
$totalHT = 100;
$totalTTC = $totalHT * 1.20; // 120€

# Alternative avec fonction dédiée
// $totalTTC = calculerTVA($totalHT);
?>

2. Les commentaires multilignes

Avec /* */, vous documentez sur plusieurs lignes. Généralement , l’objectif est de désactiver un bloc de code ou expliquer une logique complexe. Utiliser pour des blocs de code désactivés ou des mises en garde importantes.

<?php
/*
 * Fonction obsolète - remplacée par UserService::create()
 * Conservation pour compatibilité API v1
 * À supprimer après migration complète
 */
function createUserOld($name, $email) {
    // Code legacy...
}

/* TODO: Optimiser cette requête SQL
 * Index manquant sur created_at
 * Gain estimé : 40% sur les listings
 */
$users = User::where('active', 1)->get();
?>

3. Les DocBlocks

Les DocBlocks (avec /** */) sont les commentaires structurés de référence. Ils génèrent automatiquement la documentation API et aident les IDE (PHPStorm, VSCode) à l’autocomplétion. Les IDE lisent les @param, @return, @throws pour proposer l’autocomplétion intelligente.

<?php
/**
 * Calcule le prix TTC à partir du HT
 * 
 * @param float $prixHT Prix hors taxes
 * @param float $tauxTVA Taux de TVA en décimal (0.20 = 20%)
 * @return float Prix TTC arrondi à 2 décimales
 * @throws InvalidArgumentException Si prix négatif
 */
function calculerTTC(float $prixHT, float $tauxTVA): float {
    if ($prixHT < 0) {
        throw new InvalidArgumentException('Prix HT invalide');
    }
    return round($prixHT * (1 + $tauxTVA), 2);
}
?>

Quand doit-on commenter son code PHP ? La règle des 3 « P »

Commentez intelligemment avec la règle des 3 P : Pourquoi, Précondition, Postcondition.

1. Le « Pourquoi » (Pourquoi ce choix ?)

Expliquez l’intention métier ou technique, pas l’implémentation évidente.Vous pouvez d’autres développeurs en visitant des projets open-sources pour vous faire une meilleure idée.Et éventuellement demander à un autre programmeur si vos commentaires ont du sens pour lui ou non

// ❌ MAUVAIS : explique l'évident
$total = $ht + $tva; // Ajoute la TVA au HT

// ✅ BON : explique le pourquoi métier
// Application de la TVA normale (20%) et non réduite (5.5%)
// car vente B2C standard, pas de matériel agricole
$total = $ht * 1.20;

2. Les Préconditions (Quelles conditions avant exécution ?)

Documentez ce que la fonction suppose comme état initial.Vous trouverez sur Visual Studio code des extensions pour générer les commentaires à la volée pour les principaux langages de programmation tels que Java, Python, Html, Css,langage C et le langage PHP aussi.

/**
 * Envoie l'email de confirmation
 * Précondition : L'utilisateur doit être validé (status=1)
 */
function sendConfirmationEmail(User $user) {
    if ($user->status !== 1) {
        throw new LogicException('Utilisateur non validé');
    }
    // Envoi...
}

3. Les Postconditions (Quel résultat garanti ?)

Précisez ce que la fonction garantit après exécution.La plupart des langages de script sérieux annoncent le type de données qui est retourné par la fonction, méthode pour du code orienté-objet qui demande un typage strict

/**
 * Postcondition : retourne toujours un entier >= 0
 * ou lève une PageNotFoundException
 */
function getPageId(string $slug): int {
    $id = Page::where('slug', $slug)->first()?->id;
    if (!$id) {
        throw new PageNotFoundException("Page '{$slug}' introuvable");
    }
    return $id; // Toujours un entier valide
}

Quel type de code mérite d’être commenté ?

Commentez ce qui n’est pas évident au premier regard :

1. Logique métier complexe

// Application du tarif dégressif :
// -1000€ : tarif normal
// 1000-5000€ : -10%
// 5000€+ : -20% + livraison gratuite
$reduction = $montant >= 5000 ? 0.20 : ($montant >= 1000 ? 0.10 : 0);

2. Workaround ou hack temporaire

// WORKAROUND : API externe ne gère pas l'UTF-8
// Normalisation forcée avant envoi (à supprimer post-fix API)
$data = utf8_encode(utf8_decode($data));

3. Algorithmes non triviaux

// Algorithme de Levenshtein optimisé pour 95% des cas
// (distance <= 3) - gain perf x10 vs implémentation native
$distance = levenshteinFast($str1, $str2);

4. Interfaces publiques (API, classes)

Tous les DocBlocks sur les méthodes publiques. Vos collègues (et vous dans 6 mois) vous remercieront.

Ne commentez pas :

Le code auto-explicatif ($total = 100;)
Les getters/setters standards
Les implémentations triviales

Les annotations sont-elles des commentaires et à quoi servent-elles ?

Les annotations ne sont pas des commentaires PHP standards : ce sont des instructions exécutables lues par le framework et l’interpréteur au runtime ou à par le compilateur.

WordPress : Annotations pour les hooks/plugins

<?php
/* Ces commentaires sont utilisés par wordpress pour activer le plugin et donner des infos aux
 * utilisateurs dans le back office
 * Plugin Name:       My Basics Plugin
 * Plugin URI:        https://example.com/plugins/the-basics/
 * Description:       Handle the basics with this plugin.
 * Version:           1.10.3
 * Requires at least: 5.2
 * Requires PHP:      7.2
 * Author:            John Smith
 * Author URI:        https://author.example.com/
 * License:           GPL v2 or later
 * License URI:       https://www.gnu.org/licenses/gpl-2.0.html
 * Update URI:        https://example.com/my-plugin/
 * Text Domain:       my-basics-plugin
 * Domain Path:       /languages
 * Requires Plugins:  my-plugin, yet-another-plugin
 */class MonPlugin {
    
    /**
     * Ce docBlock donne des information au développeur sur ce que fait fait cette méthode de classe
     */
    public function __construct() {
        // ANNOTATION exécutable : s'enregistre automatiquement
        add_action('wp_enqueue_scripts', [$this, 'chargerStyles']);
        add_filter('the_content', [$this, 'ajouterBoutonPartage']);
    }
}
?>

Symfony : Des annotations aux attributs depuis PHP 8

Ancienne syntaxe (Annotations) , pour définir une route simple, vous écriviez 5-10 lignes de pseudo-commentaires. Les IDE peinaient à parser, les équipes perdaient du temps car il n’y avait pas de formatage disponible, et le code devenait illisible.

<?php
/**
 * @Route("/article/{id}", name="article_show")
 * @Method({"GET"})
 */
public function show(int $id) { }
?>

Moderne (Attributs PHP 8+) ,l’autocomplétion est disponible et le code est le propre et écrit plus rapidement

<?php
#[Route('/article/{id}', name: 'article_show')]
#[IsGranted('ROLE_USER')]
public function show(int $id): Response { }
?>o

Différence clé

Commentaires	Annotations/Attributs
Ignorés à l’exécution	Exécutés par le framework
Documentation humaine	Configuration automatique
`// TODO`	`#[Route]`

Les annotations ne documentent pas, elles configurent votre application. Un mélange puissant de code et de métadonnées pour la programmation web !

En résumé : Maîtrisez les 3 types de commentaires PHP + la règle des 3P pour un code professionnel. Réservez les annotations aux frameworks qui les exploitent. Votre code sera plus lisible, maintenable et apprécié par toute l’équipe !

Sources: php.net