Discussion :

[Curtis]

Ce que je veux dire, c'est que la documentation automatique est un palliatif à un code que l'on ne peut mémoriser completement non?

On peut voir ca comme ca. Il est sur qu'un projet de 50 ligne
n'a pas besoin de générateur de code. Mais pour les gros projets,
il est bien plus clair d'avoir une documentation automatique.
De plus lorsque des nouveaux développpeurs arrivent dessus
il est plus simple pour lui de parcourir la documentation automatique
et de se faire une idée des outils (bibliothèque) qu'il a à disposition
que de lui infliger une lecture de 5 milliard de lignes de codes ...

Un code clair et propre a t'il besoin de documentation de code?

Oui, mille fois oui. Meme si tu as généré un code nickel chrome,
le développeur se fou que pour la fonction ListeIMMO par exemple,
derrière se cache 12 objets et 15 fonctions. Lui il connait ce que lui
retourne la fonction et ce qu'il doit lui donner à manger. Si tu
n'a pas de générateur de code, le pauvre gars se tape tout le code
pour savoir ce que fait la fonction.

D'une documentatiion d'architecture OK, mais de documentation du code?

Et puis le problème sous jacent et bien réel des documentation qui
ne sont pas dynamiques, c'est qu'elles ne sont jamais à jour ....

D'
Le but est d'être efficace quand on code, pas d'écrire de la documentation - car le générateur de doc ne fait que centraliser les commentaires, donc à la base c'est le dévellopeur qui travaille, pas l'outils.

Malheureusement tous les développeurs qui travaillent sur des projets
ne sont pas systématiquement des développeurs comme on en rêve tous
et du coup la génération de docuementation automatique OBLIGE à une
certaine rigueur de commentaires, c'est pas plus mal non ??

Et je le repete, je travaille sur d'assez gros projet (un CMS PHP de 27000 lignes - à faire maigrir - ou un projet pro de controle de machines/pompes en Delphi)

[/quote]


Et tu n'as jamais utilisé de générateur de code, ben dis donc j'ai hate
d'avoir tes premiers sentiment sur ce genre d'outil.
Personnelement je ne l'utilise que depuis 1 an et je trouve ca franchement
pratique

[Nonothehobbit]

Ah c'est comme tout, faut pas critiquer avant d'avoir essayé, on a souvent des surprises.

[cedricgirard]

Faut penser à ceux qui n'aurotn pas le courage comme toi d'aller farfouiller dans le code. Je suis d'accord qu'on en apprend plus en allant dans le code, mais tout le monde n'éprouve pas l'envie ou le besoin de savoir vraiment comment ça se passe la dessous.

Pour une lib externe, je suis d'accord que ce n'est pas souvent utile (quoique) mais je parle là du projet sur lequel le developpeur dont on parle travaille : s'il n'est pas capable de se lancer dans le code de SON projet, il n'a rien à apporter à ce projet.

[Nonothehobbit]

Il est bien évident que si c'est pour son code, la doc ne sert à rien pour soi, mais pour ceux qui se serviront de ton travail.

[cedricgirard]

On peut voir ca comme ca. Il est sur qu'un projet de 50 ligne
n'a pas besoin de générateur de code. Mais pour les gros projets,
il est bien plus clair d'avoir une documentation automatique.

Relis mes posts, je parle de projet en entreprise, ou d'un gros projet perso, ou de projets Chrysler pour les personnes qui ont posés les bases de l'extreme programming.
Quant aux nouveaux développeurs, la doc du code ne leur sert à rien pour comprendre ce qu'ils vont faire, la seule chose qui sert est la doc d'architecture. Ensuite pour savoir quoi utiliser la meilleure chose est que les libs du projet soient nommées de manière limpide.

Un code clair et propre a t'il besoin de documentation de code?

Oui, mille fois oui. Meme si tu as généré un code nickel chrome,
le développeur se fou que pour la fonction ListeIMMO par exemple,
derrière se cache 12 objets et 15 fonctions.

Négatif, on se comprend mal. Si le code est propre, le nom de la fonction dispense le programmeur de lire ce qu'elle fait, et le dispense également de lire une doc sur cette fonction.
Et je ne génére pas du code, je l'écris. (et là je pinaille ;-))

D'une documentatiion d'architecture OK, mais de documentation du code?

Et puis le problème sous jacent et bien réel des documentation qui
ne sont pas dynamiques, c'est qu'elles ne sont jamais à jour ....

Le problème est bien là, mais peux tu te passer d'une doc d'architecture (que ce soit merise, uml ou une description en français) pour un gros projet? Peux tu la générer automatiquement? Non. Pourtant elle me semble plus utile.

Malheureusement tous les développeurs qui travaillent sur des projets ne sont pas systématiquement des développeurs comme on en rêve tous et du coup la génération de docuementation automatique OBLIGE à une certaine rigueur de commentaires, c'est pas plus mal non ??

Ca oblige à coller les commentaires au bon endroits, rien de plus. Ca n'oblige pas à écrire un texte correct dans ce commentaire, et surtout ça ne garantie en rien d'écrire du CODE correct.

Et tu n'as jamais utilisé de générateur de code, ben dis donc j'ai hate d'avoir tes premiers sentiment sur ce genre d'outil.
Personnelement je ne l'utilise que depuis 1 an et je trouve ca franchement
pratique

Tu parle de générateur de code ou de documentation? Ce n'est pas la même chose. J'ai testé phpdoc et l'outil intégré à phpedit, franchement l'avantage ne m'a pas marqué, pas plus que mes collègues. Justement j'en parle parce que j'ai testé un peu, et que cela ne m'a rien apporté.

Interessant cette discussion, j'aime

[cedricgirard]

Il est bien évident que si c'est pour son code, la doc ne sert à rien pour soi, mais pour ceux qui se serviront de ton travail.

Ben justement, ceux qui collaborent avec moi, je préfére leur laisser un code propre et compréhensible qu'ils pourront modifier facilement pour l'adapter aux nouveaux besoins plutot qu'un projet qui n'est pas compréhensible sans une doc aussi grosse que lui.
Encore une fois je ne parle pas de créer une lib à fournir aux autres, mais de collaborer à plusieurs sur un projet.

[Nonothehobbit]

Bon après c'est une question de gout mais quand j'utilise une fonction je préfère lire (au sens propre du terme) ce qu'elle fait, se qu'elle attend comme paramètre, ce qu'elle retourne, les erreur qui peuvent être levée etc plutôt que lire le nom de la fonction, des paramètres, et farfouiller dans le code pour savoir ce que la fonction retourne et son comportement quand a certains cas particulier.

De plus, pour peu que ta fonction fasse un truc un peu compliqué, t'arrive très vite à des noms de fonction de 3 kilomètre de longs.

Enfin bref, tout ça pour dire qu'une doc ou un commentaire est beaucoup plus agréable à lire que le code lui même. Le seul impératif est que tout soit bien commenté et à jour mais est-ce un mal ?

De toute façon que ce soit dans les écoles d'info ou la plupart des entreprises "organisées" (hormis celle qui font dans l'extrem programming (ça reste un extrème justement)), : code non commenté => poubelle

[Curtis]

Ca oblige à coller les commentaires au bon endroits, rien de plus. Ca n'oblige pas à écrire un texte correct dans ce commentaire, et surtout ça ne garantie en rien d'écrire du CODE correct.

C'est la que la génération de documents (et pas de code) automatique
est tout de même utile, et ou le responsable de l'application va rapidemment se rendre compte si les développeurs commentes
correctement le code, ce qui sera utile pour plus tard pour les nouveaux
arrivant. J'ai géré un projet PHP dernièrement (et codé aussi). Sur
ce projet a défilé 5 développeur différents sont intervenus(...) et la lecture
de la documentation développeur (en plus de l'architecture bien sur)
à permi aux nouveaux d'attaquer bille en tête, ce qui est pas plus
mal lorsque les délais sont courts. De plus j'ai pu rapidement donner
des conseils sur les commentaires à mettre , voir la programmation, rien qu'en
voyant la documentation généré par doxygen .

Tu parle de générateur de code ou de documentation?

Autant pour moi, de documentation bien sur

Interessant cette discussion, j'aime

Pareil ! 8)

[Nonothehobbit]

C'est bien doxygen ? Peut avoir un lien ?
Sinon essaye phpdocumentor, tu va voir moi j'adore.

Les points forts que je retiens :

- génération de doc sous plusieurs format / style (html avec frame, sans frame, pdf (à éviter c'est vraiment lourd pour une doc ), CHM (aide windows), xml...

- Installation simple (suffit de dézipper le fichier dans un répertoire)

- Possibilité de générer en ligne de commande (pratique si on veut le faire via un programme)

- Interface web super simple : on génère sa doc en 3 clic et 2 saisie au clavier (j'ai compté ) (un peu plus si on trifouiller les options)

- Possibilité de définir ses propres tag @

- Et le must du must (ça m'a bluffé), possibilité de "faire des liens" dans les fichier source. En gros quand tu as la doc sur une fonction/variable/classe, il t'affiche le numero de la ligne, tu click dessus ça t'ammène dans le fichier source à la ligne souhaité. Et dans les fichiers sources, toute les fonction php sont transformées en lien vers la doc sur php.net, et toutes les fonction/classes/methodes/variable/constante sont transformées en lien vers la page de doc correspondante (même si ça ne fait pas partie de la même classe ou du même fichier)

Et évidemment tous les truc de base, index, arborescence des classes et totu le tralala. Elle est pas belle la vie ?

Note: phpdocumentor est toujours en développement (la derniere version date de décembre), donc ça va ller sans cesse en s'améliorant.

[cedricgirard]

Bon après c'est une question de gout mais quand j'utilise une fonction je préfère lire (au sens propre du terme) ce qu'elle fait, se qu'elle attend comme paramètre, ce qu'elle retourne, les erreur qui peuvent être levée etc plutôt que lire le nom de la fonction, des paramètres, et farfouiller dans le code pour savoir ce que la fonction retourne et son comportement quand a certains cas particulier.

Est ce totalement impossible à concevoir que les commentaires ne sont qu'un palliatif? Et que l'on peut écrire du code qui soit parfaitement lisible? Le nommage des variables et fonctions est pourtant quelque chose de simple, non?

De toute façon que ce soit dans les écoles d'info ou la plupart des entreprises "organisées" (hormis celle qui font dans l'extrem programming (ça reste un extrème justement)), : code non commenté => poubelle

Ce que j'ai retenu sur "extreme" justement, c'est une gestion extremement efficace du risque. Et comme XP ne se limite pas à ça.
XP est quand même utilisé dans qq boites pas négligeables...

Je crois que le problème, le fait que tu te réfugie derriere "les écoles" et les "boites organisées" le montre bien, est qu'on a tous appris une méthode précise (cycle en V, spécifications, documentations, etc) et que l'on n'est pas vraiment capable de se rendre compte qu'elle n'est pas (plus?) adaptée à l'informatique moderne, et en tout cas pas adaptée à tous les projets.

Marrant, dans mes écoles on m'a pas tellement parlé des commentaires, mais plutot d'algos, de code, de capacité à en écrire.

[cedricgirard]

C'est bien doxygen ? Peut avoir un lien ?
Sinon essaye phpdocumentor, tu va voir moi j'adore.

http://www.google.com/search?q=doxyg...utf-8&oe=utf-8
tu as demandé un lien...

[Nonothehobbit]

Je crois que le problème, le fait que tu te réfugie derriere "les écoles" et les "boites organisées" le montre bien, est qu'on a tous appris une méthode précise (cycle en V, spécifications, documentations, etc) et que l'on n'est pas vraiment capable de se rendre compte qu'elle n'est pas (plus?) adaptée à l'informatique moderne, et en tout cas pas adaptée à tous les projets.

Marrant, dans mes écoles on m'a pas tellement parlé des commentaires, mais plutot d'algos, de code, de capacité à en écrire.

Lol tu te doute bien qu'on ne nous apprend pas que à commenter.
C'est juste une des règles à suivre pour faire un code propre, compréhensible par tous, au même titre que l'indentation, le nommage explicite des fonction et variables, etc.

Bien coder et bien commenter ne sont pas incompatible tu sais, bien sûr qu'avant tout il faut faire du bon code, mais ça ne coûte rien de le commenter, on ne fais qu'y gagner.
Tu n'y vois peut être pas d'avantage mais ça aide pas mal d'autre personnes. Tout dépend de avec qui tu travaille. Si un jour tu tombe sur quelqu'un qui a besoin de commentaire t'auras l'air bien malin avec ton xp.

A partir du moment où les commentaires ne gênent pas ceux qui n'en ont pas besoin, mieux vaut prendre l'habitude de les mettres pour le jour ou tu tombera sur quelqu'un qui en a besoin (vi ça existe. ). Bon si tu code en interne et que tu es sûr que ton code restera parmis des xtrem programmeur, on va pas t'obliger à commenter.

PS : on pourrait passer ce topic en débat non ? Avec un sondage votre générateur de doc préféré et une option "vive l'extrem programming".

[Curtis]

C'est bien doxygen ? Peut avoir un lien ?

Sur ce que je viens de lire sur phpdocumentator et phpdoc ,
doxygen est similaire. Il est à l'origine concu pour générer
de la documentation de source C ... moi je l'utilise pour
générer de la documentation sur du php,PLSQL,javascript
et je n'ai pas à me plaindre.
Il est aussi simple à installer et à configurer (peut-être pas autant
que php documentator .... mais pas bien plus). Il a toutes les
fonctionnalités cité pour phpdocumentator.

voilà.

www.doxygen.org

[xmag]

Sympa doxygen! Il fonctionne mieux que phpDocumentor (je parle pour moi là ;-)) Je n'ai pas eu de message d'erreur et c'est beaucoup plus rapide à générer. Résultat : Je suis satisfaite! Merci pour ce mini débat très agréable à lire ;-)

Sinon, pour rester un peu dans le sujet mais pas totalement tout de même, quand vous faites une architecture globale d'un projet (intranet ou internet), vous structurez cela comment? Y-a-t-il une démarche précise à suivre? Si vous avez des liens, merci :-)

[cedricgirard]

Lol tu te doute bien qu'on ne nous apprend pas que à commenter.

Je voulais juste dire que l'on ne m'a jamais fait entrer dans le crane de force que un bon code est un code commenté.

C'est juste une des règles à suivre pour faire un code propre, compréhensible par tous, au même titre que l'indentation, le nommage explicite des fonction et variables, etc.

Justement la question que je pose est "est ce necessaire de commenter?"
Le but est de faire un produit qui marche et qui est maintenable, je pense que tu es d'accord. Le reste est outil pour atteindre ce but. Et je pense que l'outil "commentaire" et l'outil "autodocumentation" ne sont pas si neccessaires que ça.

mais ça ne coûte rien de le commenter, on ne fais qu'y gagner.

Ben justement ça demande du temps à écrire, à respecter la norme de l'autodocumentateur, à mettre à jour le commentaire en meme temps que le code... Donc ça coute bien qq chose.

Tu n'y vois peut être pas d'avantage mais ça aide pas mal d'autre personnes.

Je pense que ce "besoin" est induit par une éducation bien plus que par un besoin réel. Perso j'ai besoin de commenter du Lisp, parce que je comprend mal le lisp, mais pour un langage bien maitrisé, code bien nommé et bien clair, je pose l'hypothèse que n'importe qui peut le lire efficacement.

PS : on pourrait passer ce topic en débat non ? Avec un sondage votre générateur de doc préféré et une option "vive l'extrem programming".

On pourrait en effet ;-)

[cedricgirard]

Sinon, pour rester un peu dans le sujet mais pas totalement tout de même, quand vous faites une architecture globale d'un projet (intranet ou internet), vous structurez cela comment? Y-a-t-il une démarche précise à suivre? Si vous avez des liens, merci :-)

AMHA l'archi web demanderais un sujet à part, deja traité surement ici, mais ma démarche est la suivante
- peu de pages d'entrée, deux dans mon projet actuel (vitrine et admin) pour éviter de répeter les systèmes de sécurité et les inclusions de données (tous les autres fichiers sont dans des dossiers non accessibles)
- centraliser toutes les données : DB, chemins, etc.. sous forme de constantes dans un fichier
- créer des fonctions pour inclure les librairies, qui transforment include "../libs/http.lib.php" en Librairie('http'); => en cas de changement de chemin, ça regle tout
- toujours travailler en chemin absolu, ça évite les problèmes de fichiers inclus de différents endroits
- je suis parti sur des modules, qui ont chacun des fonctions : je peux appeler la fonction "nettoyage" pour tous les modules, qui vont virer tous les trucs inutiles - conception objet en sorte
- avoir une convention de nommage forte, surtout si on pars sur des fonctions et non sur des classes pour les librairies du projet, genre utilisateur_ajouter, utilisateur_supprimer... qui se trouvent dans utilisateur.lib.php
- surtout ne jamais dupliquer un code, toujours factoriser (au sens mathématique) afin d'avoir le moins de code possible et le garder super lisible

Enfin les pratiques XP liées au code, meme si ce n'est pas vraiment de l'archi
- simplicité du code
- tests unitaires
- remaniement pour clarifier

[Nonothehobbit]

J'ai testé doxygen ça me plait pas mal, je fais vite fais un comparatif avec phpdocumentor :

Les plus :
- Génération en français (et d'autre langues aussi) !!!!!! (yeah man )
- Arborescence des classes bien foutue (j'adore le schéma des classes)
- Insertion du code directement sous la doc de la fonction (pratique)
- Génération rapide (programme compilé contrairement à phpdocumentor qui est fait en php donc plus lent)
- Supporte d'autre format (j'ai pas tout regardé)
- le chm généré est meilleur que celui de phpdocumentor (qui ne prend pas en compte la hiérarchie des classes)

: arrow: Les moins :
- Navigation un peu moins facile (faut faire beaucoup marcher la roulette)
- Impossibilité de choisir sa présentation (du moins pour ce que j'ai vu)
- Un peu galère à configurer (la prise en main est pas immédiate, mais je pense qu'après quelques manip ça doit rouler tout seul)
- Surlignage du code buggué ! Si j'ai une classe session, il me remplace partout le mot "session" par un lien sur cette classe. Même si c'est une variable ou un commentaire (ça rend le résultat un peu confu)
- seule les classes sont surlignées, pas les méthodes / fonctions et variables.

Voilà pour ce que j'en est retiré. Les 2 sont bien, j'hésite encore à changer je sais pas. Ce qu'il faut retenir c'est que les 2 sont en cours d'évolutions donc les défaut cité sont amené à disparaître et les qualité de l'un à apparaître dans l'autre.
Le point principal à retenir de doxigen est sa rapidité d'exécution et pour phpdocumentor c'est sa simplicité d'utilisation et sa convivialité (tant pour la doc que pour le générateur).

Comme toujours ce n'est qu'une question de goût. Si quelqu'un a déjà essayé dautre générateurs, qu'il nous fasse partager son avis.

[xmag]

- peu de pages d'entrée, deux dans mon projet actuel (vitrine et admin) pour éviter de répeter les systèmes de sécurité et les inclusions de données (tous les autres fichiers sont dans des dossiers non accessibles)
- centraliser toutes les données : DB, chemins, etc.. sous forme de constantes dans un fichier
- créer des fonctions pour inclure les librairies, qui transforment include "../libs/http.lib.php" en Librairie('http'); => en cas de changement de chemin, ça regle tout
- toujours travailler en chemin absolu, ça évite les problèmes de fichiers inclus de différents endroits
- je suis parti sur des modules, qui ont chacun des fonctions : je peux appeler la fonction "nettoyage" pour tous les modules, qui vont virer tous les trucs inutiles - conception objet en sorte
- avoir une convention de nommage forte, surtout si on pars sur des fonctions et non sur des classes pour les librairies du projet, genre utilisateur_ajouter, utilisateur_supprimer... qui se trouvent dans utilisateur.lib.php
- surtout ne jamais dupliquer un code, toujours factoriser (au sens mathématique) afin d'avoir le moins de code possible et le garder super lisible

Enfin les pratiques XP liées au code, meme si ce n'est pas vraiment de l'archi
- simplicité du code
- tests unitaires
- remaniement pour clarifier

Ok, merci pour ces renseignements ;-) Je vais voir si il y a d'autres sujets à ce sujet

[Frozen Bubble]

AutoPhpDoc vous connaissez ?

[Nonothehobbit]

Ca m'a l'air assez limité. Ca fait les truc standard mais pas plus, on a pas accès aux sources, tout ça...

Pas encore assez mûr à mon goût mais ça doti suffir pour les petits projets.

Bon j'ai voulu testé mais rien que l'install ça m'a lourdé...