PHPDoc

Commenter un code est la meilleure aide que vous pouvez donner aux développeurs qui réutiliseront votre code.

Pour cela, nous conseillons d'utiliser la syntaxe de PHPDoc pour vos commentaires. PHPDoc est une adaptation de JavaDoc au langage PHP. Un commentaire écrit en PHPDoc sera facilement compréhensible par un développeur ainsi que par des logiciels générateurs de documentations (PHPDocumentor, Doxygen, PHPDoc, AutoPHPDoc...). Des éditeurs de codes savent interpréter le PHPDoc pour faire de l'auto-suggestion (ex : Eclipse).

Exemples de commentaires

Commentaire sur une propriété de classe : <source lang="php">

   /**
    * Message de bienvenue
    *
    * @var    string message de bienvenue
    * @access private
    */
   var $message;

</source>

Commentaire sur une méthode de classe : <source lang="php">

   /**
    * Créé le message
    * et le stocke dans $this->message
    *
    * @access  public
    * @return  none
    */
   function creationMessage() {
      
   }

</source>

Syntaxes

On utilise la balise de commentaires pour lignes multiples : <source lang="php"> /* */ </source>

Le premier paragraphe est dédié à la description courte de l'objet commenté, le deuxième à la description longue.

Pour préciser la version d'une fonction, l'auteur d'une classe ou encore le type de l'objet, on utilise des tags préfixés par le caractère arobas @ :

Tags PHPDoc

Tag	Valeurs	Description
@abstract		L'objet est abstrait.
@access	public, private or protected	Accessibilité de l'objet.
@author	Nom de l'auteur de l'objet <emaildelauteur@email.com>	Nom et adresse e-mail de l'auteur
@copyright	nom date	Copyright.
@deprecated	version	Indique que l'objet est obsolète.
@exception		Exception lancée par une méthode (voir aussi @throws).
@global	type(string, int, boolean, array, object NomObjet...) $globalvarname	Variable globale.
@link	URL	URL associée à l'objet (redirection vers une documentation)
@package	nom du package	Nom du package de l'objet.
@param	type(string, int, boolean, array, object NomObjet...) [$varname] description	Décrit un paramètre à une fonction
@return	type(string, int, boolean, array, object NomObjet...) description	Définit la valeur de retour d'une fonction.
@static		Indique que l'objet est statique
@throws		Exception lancée par une méthode (voir aussi @throws).
@todo		Permet d'indiquer une description d'une tâche à accomplir prochainement sur l'objet.
@var	type(string, int, boolean, array, object NomObjet)	Type de la propriété
@version		Version de l'objet.

Pour plus d'informations sur les tags, vous pouvez voir ces sites : Wikipedia PHPDoc, PHPDocumentor manuel...