Commentaire PHP - Commentaires PHP
Voici comment mettre des commentaires PHP dans son code pour ensuite être capable de créé une documentation avec PHPDocumentor :
Pour toutes les pages, il faut ajouter les informations suivantes au début du fichier php :
/* * ici mettre les commentaires PHP sur le fichier en question à quoi il sert * commentaire php sur plusieurs lignes au besoin * * date modifier : 13 mars 2013 * @since 13 mars 2013 * @author Prénom Nom (courriel) * @copyright PHPascal.com * @version 1.2 * */
Pour une fonction on doit spécifier les paramêtres et les paramêtre envoyer (s'il y en a)
Exemple :
/*
* Fonction afficher sert à .. (description)
* @param $aaa = description du paramètre 1
* @param $bbb= description du paramètre 2
* @param $ccc= description du paramètre 3 avec paramètre par defaut
* @return $rrr = description de la valeur retourné
*/
function afficher($aaa,$bbb,$ccc=0)
{
.........................................
........................................
return $rrr;
}
En utilisant ce type de formatage pour construire un site web dynamique en php, ont peux par la suite faire la création d'un documentation de sont site automatiquement avec PHPDocumentor.
Il y a aussi d'autres informations qu'on peux ajouter: voir la liste complète des tags PHPDocumentor.
Dans un script idéal il devrais y avoir en moyenne une ligne de commentaire pour chaque ligne de code. Une ligne de code complexe mérite plusieurs lignes de commentaires PHP d'explication. Par contre une boucle simple de nésésite aucun commentaire PHP.
L'utilisation de variable textuel concrète nous permet d'avoir moins besoin d'utilisé de commentaire tout en ayant un code simple a comprendre. Par exemple $compteur_item pour utilisé un compteur du nombre d'item au lieu de metre $nb ou encore pire $x, $a, $zzz.