PHPfrance

la communauté d'entraide francophone dédiée au PHP

Régles/normes des commentaires

Répondre


Cette question est un moyen d’empêcher des soumissions automatisées de formulaires par des robots.
Smileys
:D :) :( :o :shock: :? 8-) :lol: :x :P :oops: :cry: :evil: :twisted: :roll: :wink: :!: :?: :idea: :arrow: :| :mrgreen: =D> #-o =P~ :^o :non: :priere: 8-|
Voir plus de smileys
  Revue du sujet
 

  Étendre la vue Revue du sujet : Régles/normes des commentaires

Re: Régles/normes des commentaires

par Genova » 31 août 2009, 15:35

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.

Re: Régles/normes des commentaires

par FuZZyLine » 31 août 2009, 15:29

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

Re: Régles/normes des commentaires

par Genova » 31 août 2009, 15:09

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.

Re: Régles/normes des commentaires

par zeus » 31 août 2009, 15:03

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 ...
 * ...
 */

Re: Régles/normes des commentaires

par Dr@ke » 31 août 2009, 14:50

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.

Re: Régles/normes des commentaires

par FuZZyLine » 31 août 2009, 14:46

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 ;)

@+ ;)

Re: Régles/normes des commentaires

par Dr@ke » 31 août 2009, 14:35

Sinon il y a le commentaire multilignes:
 /*
  Ceci est un commentaire
  sur plusieurs lignes...
*/

Re: Régles/normes des commentaires

par Genova » 31 août 2009, 14:33

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

Régles/normes des commentaires

par Cartha » 31 août 2009, 14:20

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 :

Code : Tout sélectionner

//-------------------------------------- //--- Page name : yyy.php---------- //--- Date : XX/XX/XXXX------------ //--- Last modif : XX/XX/XXXX----- //--- Version : XX.XX.XX ------------
Avant un bloc :

Code : Tout sélectionner

//--------------------------------------- // Description de ce 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 :)