Commenter son code source en PHP

By Edwige in PHP, Tutoriels 0 Comment

Dans mon entourage, et plus précisément en dehors du milieu professionnel,  la plupart des développeurs pensent que commenter son code est une perte de temps. Pour eux, il suffit simplement de le lire pour le comprendre. Cependant, ce sont ces commentaires qui qualifient la qualité et la maintenabilité d’un code. Dans cet article, je vais vous expliquer ce que permettent ces commentaires et comment les mettre en place.

Définition d’un commentaire

Un commentaire est une ligne de code non exécutée par l’interpréteur. Il peut s’écrire sur une ou plusieurs lignes.

<?php
//Ceci est un commentaire sur une ligne

/* Ceci est
*  un commentaire
*  sur plusieurs lignes
*/
?>

Le but d’un commentaire

Avant de travailler en entreprise, je réalisais des projets principalement seule. Je ne trouvais aucune utilité de commenter mon code puisque j’en étais l’auteur. Mais lorsque je suis entrée dans le milieu professionnel, j’ai tout de suite changé d’avis. L’entreprise dans laquelle je suis actuellement a développé son propre framework. Les développeurs ont pris la peine de commenter chaque classe, chaque méthode et chaque fichier. Autant vous dire que quand il n’y a pas de documentation sur le framework, cela peut se révéler bien pratique!

En résumé, les commentaires permettent de :

  • décrire un service
  • maintenir un code facilement même si l’on en est pas l’auteur

Les types de commentaires

Commenter un fichier

Commenter un fichier, plus généralement un script, permet de décrire la fonction du fichier et d’indiquer son auteur, sa version, le copyright, etc..

<?php
/**
 * Ce fichier permet de faire ceci et cela
 *
 * Ici vous pouvez donnez des détails sur le script et son fonctionnement
 *
 * @author Edwige Berteaux <edwige.berteaux@[mail].com>
 * @copyright 2014 Edwige Berteaux
 * @version 2.6
 */
//Votre script
?>

Commenter une classe

Toujours dans le but de définir le fonctionnement de telle ou telle fonctionnalité, commenter une classe se fait de la même manière que celle décrite ci-dessus.

<?php
/**
 * Cette classe permet de gérer telle ou telle entité
 *
 * @author Edwige Berteaux <edwige.berteaux@[mail].com>
 * @copyright 2014 Edwige Berteaux
 * @version 3.1
 */
class MyClass
{
    //Votre code
}
?>

Commenter une méthode

Donner plus de détails sur une méthode est nécessaire lorsque celle-ci est complexe. Vous pouvez décrire :

  • Le fonctionnement de la méthode
  • Les paramètres attendus
  • Le type de retour
  • Les erreurs attendues
<?php
/**
 * Décrire ce que fait la méthode
 *
 * @param integer $myParam1 Mon premier paramètre
 * @param string $myParam2 Mon deuxième paramètre
 *
 * @throw MyException
 *
 * @return string Un résultat
 */
public function getSomething($myParam1, $myParam2)
{
    //Votre code
}
?>

Commenter une fonctionnalité précise

Parfois, il est utile de commenter une fonctionnalité bien précise, à l’intérieur d’une méthode par exemple. On utilise pour cela le commentaire linéaire. Pour commenter un texte sur une ligne, PHP nous propose deux méthodes :

<?php
// Ceci est un commentaire linéaire
echo "Hello World";
?>

Bien rédiger ses commentaires

A la main

Vous pouvez rédiger ces commentaires sans aide de l’IDE. Voici la liste des tags que vous pouvez renseigner (la liste complète ici) :

 

Génération par l’IDE

La plupart des IDE peuvent générer automatiquement les blocs PHPDocs.

Sous Eclipse, double-cliquez sur le nom de votre fonction, faites un clic droit et cliquez sur Source/Generate Element Comment.

Sous PHPStorm, faites un clic droit sur la page, cliquez sur Generate/PHPDoc Blocks/Nom de votre méthode.

Exploiter les commentaires

Ces commentaires peuvent-être utilisés pour générer une documentation complète de votre application Web, notamment avec PHPDocumentor, Doxygen, ou encore  APIGEN.

Related Articles.

Leave a Comment.