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.
Inscrivez-vous gratuitement
pour pouvoir participer, suivre les réponses en temps réel, voter pour les messages, poser vos propres questions et recevoir la newsletter
Discussion :
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.
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.Envoyé par Curtis
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.
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.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.
Et je ne génére pas du code, je l'écris. (et là je pinaille ;-))
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.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 ....
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.
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
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.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.
Encore une fois je ne parle pas de créer une lib à fournir aux autres, mais de collaborer à plusieurs sur un projet.
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
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 .
Autant pour moi, de documentation bien sur
Pareil ! 8)
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é
- 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.
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?
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.
http://www.google.com/search?q=doxyg...utf-8&oe=utf-8C'est bien doxygen ? Peut avoir un lien ?
Sinon essaye phpdocumentor, tu va voir moi j'adore.
tu as demandé un lien...
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.
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".
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
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 :-)
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é.Lol tu te doute bien qu'on ne nous apprend pas que à commenter.
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.
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.mais ça ne coûte rien de le commenter, on ne fais qu'y gagner.
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.Tu n'y vois peut être pas d'avantage mais ça aide pas mal d'autre personnes.
On pourrait en effet ;-)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".
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
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.
Ok, merci pour ces renseignements ;-) Je vais voir si il y a d'autres sujets à ce sujet
AutoPhpDoc vous connaissez ?
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é...
Oué, moi aussi, je viens d'essayer d'installer et ça marche mal....
J'utilise aussi phpdocumentor , www.phpdoc.org
C'est génial, assez contraignant au debut, mais quand on a fais la base apres c'est facile de mettre a jour voici 2 docs de ma classe de debug avec 2 skins diffentes :
--> http://phpdebug.sourceforge.net/docu...dit/index.html
--> http://phpdebug.sourceforge.net/docu...rty/index.html
J'ai aussi trouvé une doc avec un skin qui de tueur que je vais essayer de recup
--> http://dickmann.homeunix.org/pear/ph.../Var_Dump.html
Au fait c'est un des package officiel de Pear meme s'il peut fonctionner en standalone.
Une chose que je regrette un peu dans phpdocumentor c'st que la liste des classes dans le menu de gauche ne soit pas hierarchisée comme dans doxygen. Ca aurait été super pratique. C'est prévu dans les version future ou pas ?
Répondre avec citation
Partager