Kraft.gg - Formations

Appearance

Les commentaires en PHP ​

Objectifs pédagogiques ​

  • Comprendre les différents types de commentaires disponibles en PHP.
  • Savoir les utiliser pour structurer le code, ajouter des notes, ou désactiver temporairement une portion de script.

Pourquoi commenter son code ? ​

Les commentaires servent à documenter l’intention du code. Ils facilitent sa lecture, sa maintenance, et le travail collaboratif.

Ils permettent aussi :

  • d’expliquer un algorithme complexe,
  • de désactiver une portion de code temporairement,
  • d’ajouter des métadonnées (auteur, date, etc.).

Types de commentaires en PHP ​

1. Commentaire sur une ligne ​

php
// Ceci est un commentaire
# Ceci est un autre commentaire sur une ligne

Le // est le plus couramment utilisé dans la communauté PHP.

2. Commentaire multi-lignes ​

php
/* Ceci est un
   commentaire multi-lignes */

Utile pour documenter des blocs ou des fonctions.

3. Commentaire d’annotation (PHPDoc) ​

Utilisé dans les contextes professionnels ou avec des outils d’analyse de code comme PHPStan ou PHPDocumentor :

php
/**
 * Calcule la somme de deux nombres
 *
 * @param int $a
 * @param int $b
 * @return int
 */
function sum(int $a, int $b): int {
  return $a + $b;
}

Bonnes pratiques ​

  • Éviter les commentaires évidents : // incrémente $i n'apporte aucune valeur si on lit i++.
  • Préférer un nom de variable explicite à un commentaire compensatoire.
  • Ajouter un en-tête explicatif sur les scripts principaux.

Exercice pratique ​

  1. Créer un fichier commentaire.php
  2. Y insérer trois types de commentaires :
    • sur une ligne,
    • multi-ligne,
    • PHPDoc au-dessus d'une fonction.