Programmation PHP/Commentaires
Principe
modifierLes commentaires sont en réalité des portions de texte qui ne seront pas interprétées par PHP et ne seront visibles que dans le code source. Ils jouent un rôle très important dans la réalisation et la mise à jour d'un script : en effet, les commentaires rendent le code plus lisible et peuvent aider les éventuelles personnes qui souhaitent retravailler votre script. En effet, si les commentaires sont très utiles aux programmeurs seuls, ils le sont encore plus lors du travail en équipe.
Il existe trois façons différentes d'ajouter des commentaires à son script PHP :
- La méthode avec les symboles
//pour ajouter un commentaire sur une ligne. - La méthode avec le sigle
#pour ajouter un commentaire sur une ligne également. - La méthode avec les caractères
/* */pour désigner un bloc de commentaires.
<?php
# un commentaire PHP
// encore un commentaire PHP
/* et encore
un
autre,
mais sur plusieurs lignes cette fois-ci ! */
Il est important de ne pas emboîter les commentaires. Exemple à ne pas suivre :
<?php
/*blabla /* hihi*/ blalbal*/
L'interpréteur comprendra que le commentaire s'arrête à hihi*/ et il tentera d'interpréter blalbal*/. Il en résultera donc une erreur.
Annotations
modifierIl existe des logiciels qui génèrent une documentation complète à partir des commentaires insérés dans le code du programme. De là est apparue une certaine forme de standardisation de ceux-ci afin de faciliter la génération de documentation, appelée PHPDoc. On peut en effet ajouter des commentaires structurés pour permettre de générer une documentation automatique via PEAR[1] ou PhpDocumentor. En pratique, cela se traduit par des mots-clés interprétés, précédés d'un arobase, appelés "annotations".
Exemple[2] :
/**
* Commentaires sur le rôle du fichier courant
*
* date modifier : 13 mars 2013
* @since 13 mars 2013
* @author Prénom Nom (courriel)
* @copyright PHPascal.com
* @version 1.2
*
*/
Les annotations permettent de plus, aux IDE d'en déduire l'autocomplétion, et aident les analyseurs de code statique à garantir la qualité du code. Elles étaient les seules à pouvoir préciser certains types de variables avant l'apparition des type hinting et type checking en PHP7.
Exemple de commentaires indispensables avant PHP7 :
class MyEntity
{
/** @var int|null */
private $id;
/**
* @return int|null
*/
public function getId()
{
return $this->id;
}
}
Depuis PHP7 :
class MyEntity
{
private int $id;
public function getId(): ?int
{
return $this->id;
}
}
Attributs
modifierDepuis PHP8, il existe des attributs, représentés par des mots-clés suivant un croisillon, pour préciser des informations (métadonnées) sur les classes, fonctions, constantes ou variables[3]. Ex :
<?php
#[\ReturnTypeWillChange]
public function getMixedData()
{
return $this->mixedData;
}
Cet attribut sert à ne pas ajouter de warning si le type retourné ne peut pas être déterminé[4].
Il en existe aussi d'autres comme :
- "Attribute" : pour déclarer un nouvel attribut (en précisant par exemple s'il est restreint aux fonctions).
- "Route" : pour relier une URL à une méthode.
Les attributs d'une classe peuvent être récupérés à l'exécution avec : ReflexionClass()->getAttributes().