Comprendre les commentaires PHP

Les commentaires sont des notes que vous laissez dans votre code source et que PHP ignore lors de l'exécution du programme. Ils existent uniquement pour les humains — pour expliquer pourquoi un morceau de code fait ce qu'il fait, laisser des rappels, ou désactiver temporairement du code lors du débogage. Ce guide couvre toutes les syntaxes de commentaires supportées par PHP, quand utiliser chacune d'elles, et les pratiques qui font des commentaires un atout plutôt qu'un bruit.

Ce chapitre suppose que vous savez déjà écrire du PHP de base. Sinon, commencez par les chapitres Syntaxe PHP et Variables PHP.

Que sont les commentaires PHP ?

Un commentaire est du texte dans votre code que le moteur PHP n'exécute pas. Lorsque PHP analyse un fichier, il ignore complètement les commentaires — ils n'affectent jamais la sortie, les performances ni le comportement. Ils servent de documentation pour quiconque lira le code ensuite, y compris votre futur vous-même.

PHP supporte trois styles de commentaires, qui se répartissent en deux groupes :

• Les commentaires sur une seule ligne, écrits avec // ou #.
• Les commentaires multi-lignes (blocs), écrits avec /* ... */.

PHP hérite des styles // et /* */ du C et de Java, et du style # des scripts shell et de Perl — ainsi, quelle que soit la langue dont vous venez, l'une d'elles vous semblera familière.

Commentaires sur une seule ligne

Un commentaire sur une seule ligne indique à PHP d'ignorer le reste de la ligne en cours. PHP vous propose deux marqueurs interchangeables : // (style C) et # (style shell). Ils se comportent de manière identique — choisissez-en un et restez cohérent au sein d'un projet.

<?php
// This is a single-line comment (C-style)
echo "Hello, world!";

# This is also a single-line comment (shell-style)
echo " Goodbye!";

echo " Done."; // a comment can also follow code on the same line

Le commentaire se termine au saut de ligne, donc les instructions echo s'exécutent quand même. Le script ci-dessus affiche Hello, world! Goodbye! Done.

Commentaires multi-lignes

Un commentaire multi-lignes commence par /* et se termine par */. Tout ce qui se trouve entre ces marqueurs est ignoré, même sur plusieurs lignes. Utilisez-le pour des explications plus longues ou pour commenter un bloc de code en une seule fois.

<?php
/* This is a multi-line comment.
   It can span as many lines as you need,
   which is handy for longer explanations. */
echo "Visible output";

/* You can also keep it on a single line */ echo " — still works";

Les deux instructions echo affichent Visible output — still works ; tout ce qui se trouve dans /* ... */ est ignoré.

Attention — les commentaires en bloc ne s'imbriquent pas. PHP arrête le commentaire au premier */ qu'il trouve. Si vous enveloppez du code qui contient déjà un commentaire /* ... */, le bloc externe se termine prématurément et le */ restant provoque une erreur de syntaxe. Pour désactiver un morceau de code qui contient déjà des commentaires en bloc, utilisez plutôt // ou # sur chaque ligne.

Pourquoi utiliser les commentaires PHP ?

Les commentaires PHP sont un outil important pour les développeurs, car ils aident à rendre le code plus facile à comprendre et à maintenir. En ajoutant des commentaires à votre code, vous pouvez expliquer le but de lignes de code spécifiques, ou fournir des informations supplémentaires sur le code. Cela facilite la compréhension et la maintenance du code par d'autres développeurs, et vous aide également à vous souvenir de ce que fait votre code si vous y revenez plus tard.

Comment utiliser les commentaires PHP

Pour ajouter un commentaire à votre code PHP, commencez simplement la ligne par deux barres obliques (pour les commentaires sur une seule ligne) ou une barre oblique suivie d'un astérisque (pour les commentaires multi-lignes). Il est important de choisir le type de commentaire approprié en fonction de la taille et de la complexité du code que vous commentez.

Il est également important de s'assurer que vos commentaires sont clairs et concis, et qu'ils fournissent des informations pertinentes sur le code. Évitez d'utiliser des commentaires pour simplement répéter le code, ou pour énoncer l'évidence. Concentrez-vous plutôt sur la fourniture d'informations qui ne sont pas immédiatement apparentes dans le code.

Commenter du code lors du débogage

L'une des utilisations les plus pratiques des commentaires est de désactiver temporairement du code sans le supprimer. Préfixez une ligne avec // ou #, ou enveloppez plusieurs lignes dans /* ... */, pour les retirer du programme :

<?php
$total = 10 + 5;
// echo $total;        // disabled: don't print yet
echo "Total calculated";

Souvenez-vous de la règle de non-imbrication ci-dessus : si le code que vous souhaitez désactiver contient déjà un bloc /* */, commentez-le ligne par ligne avec // à la place.

Commentaires de documentation (PHPDoc)

Au-delà des commentaires simples, l'écosystème PHP dispose d'une convention de documentation appelée PHPDoc. Il s'agit d'un commentaire en bloc qui commence par /** (deux astérisques) et utilise des balises @ pour décrire les fonctions, les paramètres et les valeurs de retour. Les IDE et les outils comme phpDocumentor les lisent pour fournir l'autocomplétion et générer la documentation API.

<?php
/**
 * Adds two numbers together.
 *
 * @param int $a The first number.
 * @param int $b The second number.
 * @return int The sum of the two numbers.
 */
function add($a, $b)
{
    return $a + $b;
}

echo add(2, 3); // 5

PHPDoc est techniquement un commentaire /* */ ordinaire pour le moteur PHP — il n'a aucun effet à l'exécution — mais suivre cette convention rend vos fonctions bien plus faciles à comprendre pour les éditeurs et vos collègues. Vous le verrez abondamment dans le chapitre Fonctions PHP.

Bonnes pratiques pour les commentaires PHP

Voici quelques bonnes pratiques à suivre lors de l'utilisation des commentaires PHP :

• Utilisez un langage clair et concis dans vos commentaires
• Évitez de répéter le code dans vos commentaires — expliquez le pourquoi, pas le quoi
• Concentrez-vous sur la fourniture d'informations qui ne sont pas immédiatement apparentes dans le code
• Utilisez des niveaux de détail appropriés dans vos commentaires
• Gardez vos commentaires à jour à mesure que votre code évolue — un commentaire obsolète est pire qu'aucun
• Préférez des noms de variables et de fonctions explicites plutôt que des commentaires qui expliquent des noms peu clairs

Conclusion

Les commentaires PHP sont un outil essentiel pour les développeurs, leur permettant de rendre leur code plus facile à comprendre et à maintenir. PHP vous propose trois syntaxes — // et # pour les lignes simples, et /* ... */ pour les blocs — ainsi que la convention PHPDoc pour documenter les fonctions. En suivant les bonnes pratiques décrites dans cet article, vous pouvez tirer le meilleur parti des commentaires PHP et vous assurer que votre code est bien documenté et facile à comprendre pour les autres développeurs.

Pour continuer à apprendre, passez à Variables PHP et Opérateurs PHP.

Practice