Documentation du code

Question

Bonjour,

Dans un soucis de clarté du code, j'aimerais bien pouvoir déclarer mes variables php en début de scripts et indiquer quelle est leur utilité.

Actuellement, je fais comme ceci :

    // *** variables ***
    $ff; // form feed
    $nombdd; // nom de la base de données
    $pth; // chemin vers la racine du site
    $ipserveur; // IP du serveur Mysql
    $table; // Une table passée en Get ?
    $bd; // objet instance de la BDD mysql

Qu'en pensez vous ? 

à+
Gilles

coucou747 · Answer

salut

c'est laid, si tu veux faire comme ca, t'as qu'a faire du java.

en general, $nombdd, on arrive a comprendre ce que c'est...

malalam · Answer

Hello,

la plupart des EDI PHP (comme Zend Studio, ou Eclipse) facilitent la documentation.
La plus usitée est sans doute PHPdoc :
http://manual.phpdoc.org/HTMLSmartyConverter/HandS/phpDocumentor/tutorial_tags.pkg.html

Je trouve plus agréable à lire ce genre de tags que tes // "inline".

cs_glad · Answer

Merci pour vos réponses 

Malalam, PhpDoc est pas mal, j'ai lu rapidemment la doc. 
Je n'y ai pas vu comment commenter une variable utiliser dans un corps de scripts (pas dans une classe).

Je sais Coucou747, c'est laid , mais parfois, il n'est pas toujours utile de tout écrire en classe... 
(à mon avis).

à++

coucou747 · Answer

glad, je parlais de la declaration de variables

dans un langage comme le php, c'est pas du tout necessaire (sauf dans une classe evidement pour pouvoir leur donner une porte)

cs_glad · Answer

Salut Coucou747,

Je sais que ce n'est pas obligatoire.

Mais ma boîte passe la certification ISO 9001-2000, et ils veulent être clean à tout les points de vue...

Donc, ils veulent que les développement s'appuient, quelques que soient les langages utilisés, sur quelques normes (commentaires du code, déclaration de variables, MCD, cahier des charges clean, etc...)

Le développement n'étant pas mon activité principale, j'essaie d'être plutôt rigoureux pour reprendre mes développements après parfois plusieurs mois d'interruption.

Je cherche juste un moyen de palier ce manque de PHP.

Je pense que le mieux est d'initialiser les variables en début de script, j'arrive sans soucis à faire des commentaires pour mes fonctions : 

 /**
 * Présentation n° tél/fax dans les résultats de la recherche
 * @param string $tel : n° de tél./fax
 * @param string $grh_numagent : n° d'agent qui a ce tél.
 * @return code HTML du n° retraité
 */
 function prestel($tel='',$grh_numagent='0')
 {
     // ...
  }

Mais pour mes variables, je cherche toujours

 /**
 * nom de la base de données
 * @var $nombdd
 * @global yes
 */
 $nombdd='annuaire';; // nom de la base de données

ça ne fonctionne pas .

Il doit y avoir un truc qui m'échappe...

à ++

Documentation du code

5 réponses

Votre réponse

Discussions similaires