PHP : la bonne pratique

PHPDoc est un standard informel pour commenter du code PHP. Il existe un grand nombre de tags disponibles. La liste complète des tags et des exemples peuvent être trouvés sur le manuel PHPDoc.

Vous trouverez ci-dessous un exemple d'utilisation des principaux tags :

<?php
/**
 * @author Votre nom <nom@exemple.com>
 * @link http://www.phpdoc.org/docs/latest/index.html
 * @package helper
 */
class DateTimeHelper
{
    /**
     * @param mixed $anything Tout ce qui peut être traduit en un objet \DateTime
     *
     * @return \DateTime
     * @throws \InvalidArgumentException
     */
    public function dateTimeFromAnything($anything)
    {
        $type = gettype($anything);

        switch ($type) {
            // Ce bloc doit retourner un objet \DateTime
        }

        throw new \InvalidArgumentException(
            "Impossible de convertir '{$type}' en un objet DateTime"
        );
    }

    /**
     * @param mixed $date Tout ce qui peut être traduit en un objet \DateTime
     *
     * @return void
     */
    public function printISO8601Date($date)
    {
        echo $this->dateTimeFromAnything($date)->format('c');
    }

    /**
     * @param mixed $date Tout ce qui peut être traduit en un objet \DateTime
     */
    public function printRFC2822Date($date)
    {
        echo $this->dateTimeFromAnything($date)->format('r');
    }
}

La documentation d'une classe commence en premier lieu par l'introduction du nom de l'auteur avec le tag @author qui peut être répété s'il y a plusieurs auteurs. En deuxième lieu, nous pouvons indiquer un lien vers un site web si jamais il existe une relation entre ce dernier et le code via le tag @link. Enfin, si jamais la classe fait partie d'un espace de noms, il faut l'indiquer avec le tag @package.

À l'intérieur de cette classe, la première méthode a un paramètre indiqué par @param qui nous renseigne sur son type, son nom et une brève description. Si jamais une méthode renvoie un résultat, il faut l'indiquer avec le tag @return et utilisez @throws autant de fois qu'il y a d'exceptions signalées.

La seconde et la troisième méthodes sont très similaires et ont un unique tag @param comme la première méthode. La seule différence notable se trouvant dans la doc. est la présence d'un tag @return sur la seconde méthode. La valeur void pour le tag @return nous informe explicitement que la méthode ne renvoie rien (si vous omettez ce tag, c'est cette valeur qui sera indiquée par défaut).

N.D.T. À noter que void n'est pas un type valide pour PHP, c'est pourquoi je préconise de mettre plutôt la valeur null qui est celle retournée par défaut quand la fonction ne contient pas d'instruction return.