Comment commenter en PHP

Informations concernant l'auteur.e

Un commentaire est un type de message qui sert à expliquer la fonction et l'objectif d'un bout de code. Avec le langage PHP, vous avez le choix entre plusieurs options, depuis les deux façons d'écrire un commentaire sur une ligne, héritage des plus vieux langages, jusqu'au commentaire sur plusieurs lignes dans le style du langage C. Les commentaires peuvent vous servir à empêcher l'exécution de paragraphes de code entiers, et vous pouvez même les utiliser pour écrire votre documentation.

Partie 1

Partie 1 sur 2:
Définir le style

1
Réservez les commentaires sur une ligne pour laisser de courtes annotations. Si vous avez besoin de faire une annotation rapide, utilisez le code de commentaire sur une ligne. Le commentaire sera pris en compte jusqu'à la fin de la ligne ou jusqu'à la fin du bloc de code. Ces commentaires fonctionneront uniquement à l'intérieur des balises PHP, et ils seront exécutés s'ils sont placés dans du code HTML ^{[1]
X
Source de recherche}.
```
 <?php
 
 // Voici la manière classique (C++) d'écrire un commentaire sur une ligne
 
# Il est également possible de faire un commentaire sur une ligne au style Unix
 
 ?>
```
2
Préférez les commentaires sur plusieurs lignes pour de longues annotations ou pour tester du code. Les commentaires sur plusieurs lignes servent à écrire une longue explication, ou à empêcher l’exécution d'un bout de code. Consultez la section suivante « Utilisation » pour découvrir des astuces sur l'utilisation des commentaires sur plusieurs lignes ^{[2]
X
Source de recherche}.
```
 <?php
 
/* Voici la manière de mettre en forme
un commentaire sur plusieurs lignes. Tout
ce qui apparait avant la balise de fin sera
inclut dans le commentaire */

/* Certaines personnes préfèrent
*  ajouter des symboles supplémentaires
*  au début de chaque ligne. Cela peut aider 
*  à améliorer la lisibilité des très longs 
*  commentaires, mais ce n'est pas indispensable.
*/

 ?>
```
Publicité

Partie 2

Partie 2 sur 2:
L'utilisation

1
Servez-vous des commentaires pour expliquer le fonctionnement de votre code. Vous ne devriez pas commenter chaque ligne de code, étant donné que du bon code bien écrit devrait être facile à comprendre et à analyser par d'autres programmeurs. Les commentaires sont utiles si le code contient des fonctions étranges ou non habituelles ^{[3]
X
Source de recherche}.
```
// Génération de la requête curl
$session = curl_init($request);
// Indique au curl d'utiliser HTTP POST
curl_setopt ($session, CURLOPT_POST, true);
```
2
Laissez des commentaires, pour que vous vous souveniez de ce que vous étiez en train de faire. Quand vous êtes en train de travailler sur des projets personnels, vous pouvez vous souvenir de l'endroit où vous vous étiez arrêté grâce aux commentaires. Commentez du code qui ne fonctionne pas correctement ou qui n'est pas encore terminé.
```
// Vérifier la sortie de cette fonction avant de continuer
echo "Hello World!";
```
3
Laissez des commentaires sur du code que vous avez l'intention de partager. Si vous avez prévu de travailler en étroite collaboration avec d'autres développeurs, ou si vous pensez publier votre code pour le rendre open source, d'autres développeurs peuvent comprendre le fonctionnement de votre code grâce aux commentaires, et ils peuvent ainsi réfléchir à des manières de l'améliorer plus efficacement ^{[4]
X
Source de recherche}.
```
/* Il existe une technique plus efficace pour faire ça ? */
Genre:
<input type="radio" name="genre"
<?php if (isset($genre) && $genre=="femme") echo "checked";?>
value="femme">Femme
<input type="radio" name="genre"
<?php if (isset($genre) && $genre=="homme") echo "checked";?>
value="homme">Homme
```
4
Servez-vous des commentaires pour empêcher l'exécution d'un bloc de code en particulier. Si vous êtes en train de tester une fonctionnalité et que vous voulez éviter qu'une certaine portion de code s'exécute, utilisez cette technique. Tout ce qui est compris entre les deux balises de commentaires sera ignoré quand la page se chargera.
```
 <?php
 
echo "/*Hello*/ World!";
 
 /* Le mot « Hello » ne sera pas affiché
quand le code ci-dessus sera exécuté */
 
 ?>
```
5
Faites attention quand vous commentez de gros blocs de code. Le commentaire prendra fin quand il arrivera à la première balise de fin qu'il rencontrera, peu importe où elle se trouve. S'il y a déjà un commentaire sur plusieurs lignes dans la portion de code que vous êtes en train de commenter, votre nouveau commentaire sera pris en compte seulement jusqu'à la balise de fin du commentaire déjà présent dans le bloc de code.
```
 <?php
 
 /* 
echo "Hello World!"; /* Ce commentaire va tout casser */
*/

 ?>
```
```
 <?php
 
 /* 
echo "Hello World!"; // Ce commentaire sera très bien pris en compte
*/

 ?>
```
6
Servez-vous des commentaires pour écrire une documentation factice. Si vous êtes créatif avec votre format de code, vous pouvez rédiger la documentation de votre code directement dans le code. C'est très utile dans le cas des projets open source.
```
 <?php
 
 //=============
 // TITRE
 //=============
 
 //-------------
 // Sous-titre
 //-------------
 
/* Titre de la section */
 
# Ici se trouve la documentation
# Une autre explication va ici
 
 /*
 * Utilisez-les pour expliquer quelque chose
 * qui aurait normalement besoin
 * de plusieurs lignes, voire de plusieurs 
 * paragraphes pour être expliqué
 */
 
 ?>
```
Publicité

Conseils

Les commentaires en HTML et en PHP sont différents, ce qui signifie que lorsque vous écrivez des scripts (mélange de HTML et de PHP), faites attention de ne pas mélanger les commentaires.
Par exemple, dans le code ci-dessous, vous trouverez un commentaire HTML, mais le code PHP est quand même exécuté. Le fait de placer un commentaire HTML à l'intérieur de balises PHP va provoquer des erreurs.
-