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

Common tags

Tag	Usage	Description
@abstract		Documents an abstract class, class variable or method.
@access	public, private or protected	Documents access control for an element. @access private indicates that documentation of element be prevented.
@author	author name <author@email>	Documents the author of the current element.
@copyright	name date	Documents copyright information.
@deprecated	version	Documents a method as deprecated.
@deprec		same as @deprecated
@example	/path/to/example	Documents the location of an external saved example file.
@exception		documents an exception thrown by a method — also see @throws.
@global	type $globalvarname	Documents a global variable or its use in a function or method.
@ignore		Prevents the documentation of an element
@internal		private information for advanced developers
@link	URL
@name	global variable name	Specifies an alias for a variable. For example, $GLOBALS['myvariable'] becomes $myvariable
@magic
@package	name of a package	Documents a group of related classes and functions.
@param	type [$varname] description
@return	type description	This tag should not be used for constructors or methods defined with a void return type.
@see		Documents an association to another method or class.
@since	version	Documents when a method was added to a class.
@static		Documents a static class or method
@staticvar		Documents a static variable's use in a function or class
@subpackage
@throws		Documents an exception thrown by a method.
@todo		Documents things that need to be done to the code at a later date.
@var	type	a data type for a class variable
@version		Provides the version number of a class or method.

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