« Programmation PHP/Commentaires » : différence entre les versions

Un livre de Wikilivres.
Contenu supprimé Contenu ajouté
Ligne 48 : Ligne 48 :
Les annotations permettent de plus, aux IDE d'en déduire l'autocomplétion, et aident les [[Programmation_PHP/Concevoir_du_code_de_haute_qualité#Outils_d'analyse_de_code|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 checking en PHP7.
Les annotations permettent de plus, aux IDE d'en déduire l'autocomplétion, et aident les [[Programmation_PHP/Concevoir_du_code_de_haute_qualité#Outils_d'analyse_de_code|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 checking en PHP7.


Exemple de commentaires indispensables avant PHP7 :
Autre exemple :
<syntaxhighlight lang=php>
<syntaxhighlight lang=php>
class MyEntity
class MyEntity
Ligne 59 : Ligne 59 :
*/
*/
public function getId()
public function getId()
{
return $this->id;
}
}
</syntaxhighlight>

Depuis PHP7 :
<syntaxhighlight lang=php>
class MyEntity
{
private int $id;

public function getId(): ?int
{
{
return $this->id;
return $this->id;

Version du 28 décembre 2021 à 12:03

Principe

Les 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 :

  1. La méthode avec les symboles // pour ajouter un commentaire sur une ligne.
  2. La méthode avec le sigle # pour ajouter un commentaire sur une ligne également.
  3. 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 ! */

Logo

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

Il 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 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;
    }
}

Références