J'ai récupéré un site php en POO (avec des classes dédiées pour les
structure des données, les interactions avec la BD, le traitement des
données reçues du client, l'envoi de données au client, etc.). Je
voudrais le documenter de façon clean.
Qu'est ce qui existe comme outil facilitant la documentation ? J'ai vu
sur des articles anciens que PHPdoc était censé émuler JavaDoc mais il
semble en version beta depuis des lustres...
J'ai fait une petite recherche, et j'ai trouvé "PhpDocumentor", Le projet est réalisé à 98% ... Ca vaut peut-être le coup de regarder ... http://sourceforge.net/projects/phpdocu/
A+
Bonsoir,
J'ai fait une petite recherche, et j'ai trouvé "PhpDocumentor", Le projet
est réalisé à 98% ...
Ca vaut peut-être le coup de regarder ...
http://sourceforge.net/projects/phpdocu/
J'ai fait une petite recherche, et j'ai trouvé "PhpDocumentor", Le projet est réalisé à 98% ... Ca vaut peut-être le coup de regarder ... http://sourceforge.net/projects/phpdocu/
J'ai récupéré un site php en POO (avec des classes dédiées pour les structure des données, les interactions avec la BD, le traitement des données reçues du client, l'envoi de données au client, etc.). Je voudrais le documenter de façon clean.
vi. emacs. word. Lors de l'ANALYSE DU PROJET/DU BESOIN.
<position à contre courant> Les commentaires dans le code c'est vital. C'est pour les générations de développeurs qui viendront après sur le projet. On écrit d'abord les commentaires, puis on rempli avec le code.
La documentation du fonctionnement général des modules, c'est AVANT d'écrire le code que ça s'écrit. Ca n'a RIEN a voir avec le codage.
ARRETEZ DE POURRIR LE CODE SOURCE AVEC DU #@! DE BLABLA QUI N'A RIEN A Y FOUTRE. C'est totalement illisible, et je parle même pas d'essayer de faire un cvs diff entre deux fichiers une fois qu'ils ont été ouverts par deux éditeurs différents. </position à contre courant>
a++ JG
'alut,
J'ai récupéré un site php en POO (avec des classes dédiées pour les
structure des données, les interactions avec la BD, le traitement des
données reçues du client, l'envoi de données au client, etc.). Je
voudrais le documenter de façon clean.
vi. emacs. word. Lors de l'ANALYSE DU PROJET/DU BESOIN.
<position à contre courant>
Les commentaires dans le code c'est vital. C'est pour les générations de
développeurs qui viendront après sur le projet. On écrit d'abord les
commentaires, puis on rempli avec le code.
La documentation du fonctionnement général des modules, c'est AVANT
d'écrire le code que ça s'écrit. Ca n'a RIEN a voir avec le codage.
ARRETEZ DE POURRIR LE CODE SOURCE AVEC DU #@! DE BLABLA QUI N'A RIEN A Y
FOUTRE. C'est totalement illisible, et je parle même pas d'essayer de
faire un cvs diff entre deux fichiers une fois qu'ils ont été ouverts par
deux éditeurs différents.
</position à contre courant>
J'ai récupéré un site php en POO (avec des classes dédiées pour les structure des données, les interactions avec la BD, le traitement des données reçues du client, l'envoi de données au client, etc.). Je voudrais le documenter de façon clean.
vi. emacs. word. Lors de l'ANALYSE DU PROJET/DU BESOIN.
<position à contre courant> Les commentaires dans le code c'est vital. C'est pour les générations de développeurs qui viendront après sur le projet. On écrit d'abord les commentaires, puis on rempli avec le code.
La documentation du fonctionnement général des modules, c'est AVANT d'écrire le code que ça s'écrit. Ca n'a RIEN a voir avec le codage.
ARRETEZ DE POURRIR LE CODE SOURCE AVEC DU #@! DE BLABLA QUI N'A RIEN A Y FOUTRE. C'est totalement illisible, et je parle même pas d'essayer de faire un cvs diff entre deux fichiers une fois qu'ils ont été ouverts par deux éditeurs différents. </position à contre courant>
a++ JG
Etienne SOBOLE
"John GALLET" a écrit dans le message de news:
Les commentaires dans le code c'est vital. C'est pour les générations de développeurs qui viendront après sur le projet. On écrit d'abord les commentaires, puis on rempli avec le code.
Interessante position. Cela me semble pourtant, meme si j'aurai tendance a abonder dans ton sens... utopique. La plupart des developpeurs PHP travaillent sur des projets de petite envergure (j'entends par là moins d'une année/homme) Et donc il faut bien reconnaitre que les exigences de temps de developpement empèche complètement ce genre de prétraitement.
Il y a un excellent article "La cathedrale et la bazar", qui sans vanter l'une ou l'autre des approches les étudies toutes les deux et montre les limites de l'une et de l'autre. Enfin il parle de projet qui ont été réalisé dans les deux modes! Tu seras surpris de voir les projets réalisés dans le "bordel" dirais-je
le lien: http://www.linux-france.org/article/these/cathedrale-bazar/cathedrale-bazar_monoblock.html
Etienne
"John GALLET" <john.gallet@wanadoo.fr> a écrit dans le message de news:
Pine.LNX.4.44.0409302127370.27471-100000@ns2261.ovh.net...
Les commentaires dans le code c'est vital. C'est pour les générations de
développeurs qui viendront après sur le projet. On écrit d'abord les
commentaires, puis on rempli avec le code.
Interessante position.
Cela me semble pourtant, meme si j'aurai tendance a abonder dans ton sens...
utopique.
La plupart des developpeurs PHP travaillent sur des projets de petite
envergure (j'entends par là moins d'une année/homme)
Et donc il faut bien reconnaitre que les exigences de temps de developpement
empèche complètement ce genre de prétraitement.
Il y a un excellent article
"La cathedrale et la bazar", qui sans vanter l'une ou l'autre des approches
les étudies toutes les deux et montre les limites de l'une et de l'autre.
Enfin il parle de projet qui ont été réalisé dans les deux modes!
Tu seras surpris de voir les projets réalisés dans le "bordel" dirais-je
le lien:
http://www.linux-france.org/article/these/cathedrale-bazar/cathedrale-bazar_monoblock.html
Les commentaires dans le code c'est vital. C'est pour les générations de développeurs qui viendront après sur le projet. On écrit d'abord les commentaires, puis on rempli avec le code.
Interessante position. Cela me semble pourtant, meme si j'aurai tendance a abonder dans ton sens... utopique. La plupart des developpeurs PHP travaillent sur des projets de petite envergure (j'entends par là moins d'une année/homme) Et donc il faut bien reconnaitre que les exigences de temps de developpement empèche complètement ce genre de prétraitement.
Il y a un excellent article "La cathedrale et la bazar", qui sans vanter l'une ou l'autre des approches les étudies toutes les deux et montre les limites de l'une et de l'autre. Enfin il parle de projet qui ont été réalisé dans les deux modes! Tu seras surpris de voir les projets réalisés dans le "bordel" dirais-je
le lien: http://www.linux-france.org/article/these/cathedrale-bazar/cathedrale-bazar_monoblock.html
Etienne
P'tit Marcel
Mon enfant,
J'ai récupéré un site php en POO. Je voudrais le documenter de façon clean.
vi. emacs. word. Lors de l'ANALYSE DU PROJET/DU BESOIN.
on ne parle pas de la même chose. Je veux documenter le fait que tel script php est appelé par un autre (require/include), que telle classe est utilisée ou définie dans tel script, etc. Je préfère que ces correspondances soient établies automatiquement dans la doc pour être sûr que celle-ci n'oublie rien et reste à jour.
Pour tout ça, je ne vois pas en quoi vi m'aiderait, ni même wordstar ou ibm/xedit (pour rester dans la préhistoire).
a+ -- p'tit Marcel
Mon enfant,
J'ai récupéré un site php en POO. Je
voudrais le documenter de façon clean.
vi. emacs. word. Lors de l'ANALYSE DU PROJET/DU BESOIN.
on ne parle pas de la même chose. Je veux documenter le fait que tel
script php est appelé par un autre (require/include), que telle classe
est utilisée ou définie dans tel script, etc. Je préfère que ces
correspondances soient établies automatiquement dans la doc pour être
sûr que celle-ci n'oublie rien et reste à jour.
Pour tout ça, je ne vois pas en quoi vi m'aiderait, ni même wordstar ou
ibm/xedit (pour rester dans la préhistoire).
J'ai récupéré un site php en POO. Je voudrais le documenter de façon clean.
vi. emacs. word. Lors de l'ANALYSE DU PROJET/DU BESOIN.
on ne parle pas de la même chose. Je veux documenter le fait que tel script php est appelé par un autre (require/include), que telle classe est utilisée ou définie dans tel script, etc. Je préfère que ces correspondances soient établies automatiquement dans la doc pour être sûr que celle-ci n'oublie rien et reste à jour.
Pour tout ça, je ne vois pas en quoi vi m'aiderait, ni même wordstar ou ibm/xedit (pour rester dans la préhistoire).
a+ -- p'tit Marcel
Michel BONZI
Mon enfant,
J'ai récupéré un site php en POO. Je voudrais le documenter de façon clean.
vi. emacs. word. Lors de l'ANALYSE DU PROJET/DU BESOIN.
on ne parle pas de la même chose. Je veux documenter le fait que tel script php est appelé par un autre (require/include), que telle classe est utilisée ou définie dans tel script, etc. Je préfère que ces correspondances soient établies automatiquement dans la doc pour être sûr que celle-ci n'oublie rien et reste à jour.
Pour tout ça, je ne vois pas en quoi vi m'aiderait, ni même wordstar ou ibm/xedit (pour rester dans la préhistoire).
a+ Bonjour,
PhpDocumentor : http://phpdoc.org/index.php - Liste des fonctions, des classes par ordre alphabétique, fichier ou elle sont définies, les commentaires /** sont ajoutés dans la doc.... C'est utile. Salutation. Michel BONZI
Mon enfant,
J'ai récupéré un site php en POO. Je voudrais le documenter de façon
clean.
vi. emacs. word. Lors de l'ANALYSE DU PROJET/DU BESOIN.
on ne parle pas de la même chose. Je veux documenter le fait que tel
script php est appelé par un autre (require/include), que telle classe
est utilisée ou définie dans tel script, etc. Je préfère que ces
correspondances soient établies automatiquement dans la doc pour être
sûr que celle-ci n'oublie rien et reste à jour.
Pour tout ça, je ne vois pas en quoi vi m'aiderait, ni même wordstar ou
ibm/xedit (pour rester dans la préhistoire).
a+
Bonjour,
PhpDocumentor : http://phpdoc.org/index.php
- Liste des fonctions, des classes par ordre alphabétique, fichier ou
elle sont définies, les commentaires /** sont ajoutés dans la doc....
C'est utile.
Salutation.
Michel BONZI
J'ai récupéré un site php en POO. Je voudrais le documenter de façon clean.
vi. emacs. word. Lors de l'ANALYSE DU PROJET/DU BESOIN.
on ne parle pas de la même chose. Je veux documenter le fait que tel script php est appelé par un autre (require/include), que telle classe est utilisée ou définie dans tel script, etc. Je préfère que ces correspondances soient établies automatiquement dans la doc pour être sûr que celle-ci n'oublie rien et reste à jour.
Pour tout ça, je ne vois pas en quoi vi m'aiderait, ni même wordstar ou ibm/xedit (pour rester dans la préhistoire).
a+ Bonjour,
PhpDocumentor : http://phpdoc.org/index.php - Liste des fonctions, des classes par ordre alphabétique, fichier ou elle sont définies, les commentaires /** sont ajoutés dans la doc.... C'est utile. Salutation. Michel BONZI
John GALLET
Mon enfant, ;-))
on ne parle pas de la même chose. meuuuuh si. Quoique ... en effet.
Je veux documenter le fait que tel script php est appelé par un autre (require/include),
C'est un commentaire pour le développeur : attention, toute modification de ce script peut avoir un impact sur tel et tel autre, mais qui doit bien rester dans le code car elle a trait au fonctionnement interne du logiciel.
que telle classe est utilisée ou définie dans tel script, etc. Je préfère que ces correspondances soient établies automatiquement dans la doc pour être sûr que celle-ci n'oublie rien et reste à jour.
J'ai l'impression qu'on a pas la même définition de "documentation". Chez moi la doc, c'est fonctionnel, c'est un document externe décrivant les grandes lignes du but du logiciel, module par module, pouvant descendre si nécessaire dans le détail de codes retours / des exceptions. Ca s'écrit si possible avant de coder, sinon en reverse-engineering. C'est livrable au client s'il le demande. La documentation interne à destinatin du développeur, ça se fait clairement AVANT de coder sinon ça sert plus à grand chose (à peine à intégrer les nouveaux arrivants sur un projet) et ça ne remplacera JAMAIS des commentaires explicites directement dans le code.
Je sais que cetet position est "à contre courant" ou "pas à la mode", mais j'en ai vraiment RAS LE BOL de ces putains de trucs illisibles pour [doxygen|javadoc|etc...] qui pourrissent le code. Mais bon, c'est mon avis et je le partage ;-)
a++ JG
Mon enfant,
;-))
on ne parle pas de la même chose.
meuuuuh si. Quoique ... en effet.
Je veux documenter le fait que tel
script php est appelé par un autre (require/include),
C'est un commentaire pour le développeur : attention, toute modification
de ce script peut avoir un impact sur tel et tel autre, mais qui doit bien
rester dans le code car elle a trait au fonctionnement interne du
logiciel.
que telle classe
est utilisée ou définie dans tel script, etc. Je préfère que ces
correspondances soient établies automatiquement dans la doc pour être
sûr que celle-ci n'oublie rien et reste à jour.
J'ai l'impression qu'on a pas la même définition de "documentation". Chez
moi la doc, c'est fonctionnel, c'est un document externe décrivant les
grandes lignes du but du logiciel, module par module, pouvant descendre si
nécessaire dans le détail de codes retours / des exceptions. Ca s'écrit si
possible avant de coder, sinon en reverse-engineering. C'est livrable au
client s'il le demande. La documentation interne à destinatin du
développeur, ça se fait clairement AVANT de coder sinon ça sert plus à
grand chose (à peine à intégrer les nouveaux arrivants sur un projet) et
ça ne remplacera JAMAIS des commentaires explicites directement dans le
code.
Je sais que cetet position est "à contre courant" ou "pas à la mode", mais
j'en ai vraiment RAS LE BOL de ces putains de trucs illisibles pour
[doxygen|javadoc|etc...] qui pourrissent le code. Mais bon, c'est mon avis
et je le partage ;-)
on ne parle pas de la même chose. meuuuuh si. Quoique ... en effet.
Je veux documenter le fait que tel script php est appelé par un autre (require/include),
C'est un commentaire pour le développeur : attention, toute modification de ce script peut avoir un impact sur tel et tel autre, mais qui doit bien rester dans le code car elle a trait au fonctionnement interne du logiciel.
que telle classe est utilisée ou définie dans tel script, etc. Je préfère que ces correspondances soient établies automatiquement dans la doc pour être sûr que celle-ci n'oublie rien et reste à jour.
J'ai l'impression qu'on a pas la même définition de "documentation". Chez moi la doc, c'est fonctionnel, c'est un document externe décrivant les grandes lignes du but du logiciel, module par module, pouvant descendre si nécessaire dans le détail de codes retours / des exceptions. Ca s'écrit si possible avant de coder, sinon en reverse-engineering. C'est livrable au client s'il le demande. La documentation interne à destinatin du développeur, ça se fait clairement AVANT de coder sinon ça sert plus à grand chose (à peine à intégrer les nouveaux arrivants sur un projet) et ça ne remplacera JAMAIS des commentaires explicites directement dans le code.
Je sais que cetet position est "à contre courant" ou "pas à la mode", mais j'en ai vraiment RAS LE BOL de ces putains de trucs illisibles pour [doxygen|javadoc|etc...] qui pourrissent le code. Mais bon, c'est mon avis et je le partage ;-)
a++ JG
Bruno Desthuilliers
John GALLET wrote:
ARRETEZ DE POURRIR LE CODE SOURCE AVEC DU #@! DE BLABLA QUI N'A RIEN A Y FOUTRE.
<aol>Dans mes bras !!!</aol>
John GALLET wrote:
ARRETEZ DE POURRIR LE CODE SOURCE AVEC DU #@! DE BLABLA QUI N'A RIEN A Y
FOUTRE.
ARRETEZ DE POURRIR LE CODE SOURCE AVEC DU #@! DE BLABLA QUI N'A RIEN A Y FOUTRE.
<aol>Dans mes bras !!!</aol>
Bruno Desthuilliers
P'tit Marcel wrote: (snip)
on ne parle pas de la même chose. Je veux documenter le fait que tel script php est appelé par un autre (require/include), que telle classe est utilisée ou définie dans tel script, etc. Je préfère que ces correspondances soient établies automatiquement dans la doc pour être sûr que celle-ci n'oublie rien et reste à jour.
grep est ton ami, et tu es *sûr* que c'est à jour !-)
Bon, modérons un peu le propos. Je ne dis pas qu'un peu de doc dans le code soit inutile, surtout pour les passages pas évidents. Par contre, les trucs à la javadoc ont tendance à me fâcher légèrement - je suis d'accord avec John sur la perte de lisibilité, et puis ces commentaires ont une nette tendance à ne pas être jour.
Toi, je ne sais pas, mais personnellement je préfère pas de doc du tout à une doc mensongère !-)
Bruno
P'tit Marcel wrote:
(snip)
on ne parle pas de la même chose. Je veux documenter le fait que tel
script php est appelé par un autre (require/include), que telle classe
est utilisée ou définie dans tel script, etc. Je préfère que ces
correspondances soient établies automatiquement dans la doc pour être
sûr que celle-ci n'oublie rien et reste à jour.
grep est ton ami, et tu es *sûr* que c'est à jour !-)
Bon, modérons un peu le propos. Je ne dis pas qu'un peu de doc dans le
code soit inutile, surtout pour les passages pas évidents. Par contre,
les trucs à la javadoc ont tendance à me fâcher légèrement - je suis
d'accord avec John sur la perte de lisibilité, et puis ces commentaires
ont une nette tendance à ne pas être jour.
Toi, je ne sais pas, mais personnellement je préfère pas de doc du tout
à une doc mensongère !-)
on ne parle pas de la même chose. Je veux documenter le fait que tel script php est appelé par un autre (require/include), que telle classe est utilisée ou définie dans tel script, etc. Je préfère que ces correspondances soient établies automatiquement dans la doc pour être sûr que celle-ci n'oublie rien et reste à jour.
grep est ton ami, et tu es *sûr* que c'est à jour !-)
Bon, modérons un peu le propos. Je ne dis pas qu'un peu de doc dans le code soit inutile, surtout pour les passages pas évidents. Par contre, les trucs à la javadoc ont tendance à me fâcher légèrement - je suis d'accord avec John sur la perte de lisibilité, et puis ces commentaires ont une nette tendance à ne pas être jour.
Toi, je ne sais pas, mais personnellement je préfère pas de doc du tout à une doc mensongère !-)
Bruno
Seb
J'ai récupéré un site php en POO (avec des classes dédiées pour les structure des données, les interactions avec la BD, le traitement des données reçues du client, l'envoi de données au client, etc.). Je voudrais le documenter de façon clean.
Qu'est ce qui existe comme outil facilitant la documentation ? J'ai vu sur des articles anciens que PHPdoc était censé émuler JavaDoc mais il semble en version beta depuis des lustres...
Bonjour,
Je me sers depuis quelques années de Doxygen, j'en suis très content :). http://www.stack.nl/~dimitri/doxygen/
@+ Séb
J'ai récupéré un site php en POO (avec des classes dédiées pour les
structure des données, les interactions avec la BD, le traitement des
données reçues du client, l'envoi de données au client, etc.). Je
voudrais le documenter de façon clean.
Qu'est ce qui existe comme outil facilitant la documentation ? J'ai vu
sur des articles anciens que PHPdoc était censé émuler JavaDoc mais il
semble en version beta depuis des lustres...
Bonjour,
Je me sers depuis quelques années de Doxygen, j'en suis très content :).
http://www.stack.nl/~dimitri/doxygen/
J'ai récupéré un site php en POO (avec des classes dédiées pour les structure des données, les interactions avec la BD, le traitement des données reçues du client, l'envoi de données au client, etc.). Je voudrais le documenter de façon clean.
Qu'est ce qui existe comme outil facilitant la documentation ? J'ai vu sur des articles anciens que PHPdoc était censé émuler JavaDoc mais il semble en version beta depuis des lustres...
Bonjour,
Je me sers depuis quelques années de Doxygen, j'en suis très content :). http://www.stack.nl/~dimitri/doxygen/
