Forum d'entraide PHPFrance

Bonjour à tous

Je me demandais depuis quelques temps s'il existe des règles précises pour noter les commentaires dans un fichiers php.
Jusqu'au là je me contentais de ma propre imagination en établissant des règles à ma manière, genre :

Au début d'un fichier php : Avant un bloc : etc...

Est-ce qu'il existe des normes ou des règles bien déterminées à respecter ou bien je contenu ce que je fais ?

Merci pour votre aide et bonne journée à tous

Il y a la norme PHPdoc qui te permet de générer une documentation de ton projet à partir des commentaires.

http://manual.phpdoc.org/HTMLSmartyConv ... r.pkg.html

Sinon il y a le commentaire multilignes:

 /*
  Ceci est un commentaire
  sur plusieurs lignes...
*/

Salut tout seul,

Bonjour à tous
Je me demandais depuis quelques temps s'il existe des règles précises pour noter les commentaires dans un fichiers php.
Jusqu'au là je me contentais de ma propre imagination en établissant des règles à ma manière, genre :
Au début d'un fichier php :
[...]
etc...
Est-ce qu'il existe des normes ou des règles bien déterminées à respecter ou bien je contenu ce que je fais ?
Merci pour votre aide et bonne journée à tous

Il y a environ autant de façon de noter les commentaires qu'il existe de codeurs...

1) # REM
2) // REM
3) /* REM */

Avec les 3 types de commentaitres, ci-dessus, je te laisse imaginer les possibilités de mise en page etc...

A mon sens, si une certaine harmonie existe en ce domaine, c'est juste afin que les scripts soient
parsés correctement par des applis telles "PhpDocumentor". Ceci dit c'est mon point de vu et celui-ci
n'engage que moi

@+

Il n'empêche que le commentaire multilignes est la seule façon propre et lisible de faire un commentaire sur plusieurs lignes...
Donc pour ton exemple, le commentaire multilignes me parait la meilleur solution.

Il n'empêche que le commentaire multilignes est la seule façon propre et lisible de faire un commentaire sur plusieurs lignes...
Donc pour ton exemple, le commentaire multilignes me parait la meilleur solution.

L'un n'empêche pas l'autre.

Le phpDoc est LA référence, celle qui est reconnue et connue par la majorité des développeurs.
Et cette norme s'appuie sur une variante du commentaire sur plusieurs lignes :

/**
 * Description courte
 * 
 * Description longue sur plusieurs lignes si nécessaire
 * 
 * @author zeus
 * @since ...
 * @version ...
 * ...
 */

En ce qui me concerne je suis passé à la syntaxe phpdoc depuis que je suis passé sous Zend Studio, puisque ce dernier se sert de ces commentaires pour améliorer la complétion.

Exemple :

/**
 * Do something
 *
 * @return MyClass
 */
function foo()
{
   (...)
}

Lorsque je tape sous Zend Studio le code ci dessous (le | représente le curseur) :

$var = foo();
$var->|

il me propose en auto complétion les propriétés et méthodes publiques de ma classe MyClass.

Si je peux me permetre un conseil après tout ce qui a été dit... (non? je peux pas? grrr!!!

Quand on code la meilleur des habitudes est de se dire: Quelqu'un passera derriere moi.
Autrement dit:

Est ce que mon code sera compréhensible?
Sera t'il facile à lire/à décoder?

Les commentaires valant compréhension (plus ou moins) à toi de voir quels seront les types
de commentaires à employer et comment. phpDoc est une très bonne méthode, beaucoup
de codeurs l'utilise et passé la barriere "du changement" ca facilite pas mal les choses, je trouve.

Voila, pas vraiment une norme mais ca y ressemble

Encore une fois c'est qu'un avis perso

@+

PS: je déteste l'auto complétion

L'auto complétion n'est pas obligatoire, Zend te propose des choix mais si tu continues à écrire sans sélectionner un des choix il ne se passe rien. Quand tu bosses avec un gros Framework c'est ultra pratique d'avoir à portée de main les noms de méthodes, leurs paramètres, les valeurs de retour sans avoir à aller les chercher dans le code ou lire la documentation.