Envoyé par Nebulix
Soit tu n'as pas lu le thread, soit tu ne l'as pas compris...
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 :
Soit tu n'as pas lu le thread, soit tu ne l'as pas compris...
la question reste toujours la même
Dans la question assez longue de skip, il me semble que l'essentiel est :
Une condition nécessaire, à mon avis :la question reste toujours la même : Comment faire pour que ce soit bien, sans être superflu et chronophage?
Pour faire quelque chose de "bien" (que je traduis "utile"), il faut d'abord penser à qui et à quoi celà sera utile, avec ses méninges, avant de se ruer sur son clavier et lancer CodeChose ou TrucSoft.
Je ne pensais pas choquer en écrivant celà...
Ca me choque pas vraiment.
Il est question principalement de documentation de projet, pas vraiment de manuel utilisateur. A moins qu'on puisse estimer que certains modules nécessitent une documentation utilisateur comme par exemple les arguments d'un exécutable en ligne de commande utilisé par le système.
Les questions concernent principalement la communication d'information au sein de l'équipe.
Pour l'instant j'ai 2 personnes qui ont dit qu'elles passaient environ 30% de leurs temps sur de la doc.
Moi , pour ma part, doc programmeur EXTERNE, je dirais environ au max 1% du temps.
Doc programmeur interne (commentaires, entêtes, etc), sans doute environ 2-3% du temps.
La doc externe la plus longue que j'ai eu à faire (un dictionnaire à usage de l'équipe): 2 mois de boulot pour 2 ans d'un projet de 60 personnes, soit 2/24*60 = 0.14% du projet, et pour moi-même 8.3% ...
à propos du manuel utilisateur
Le texte de départ citait explicitement le "manuel utilisateur" et couvrait beaucoup de sujets méritant discussion
Voilà déjà des destinataires mieux précisés.
Néanmoins je pense qu'il faudrait aussi revoir le découpage des différentes documentations. Par exemple le manuel utilisateur est un bon endroit où placer
ce qui devrait intéresser l'équipe de développement et qu'on omet très souvent, tu as raison de le souligner...en gros que fait le programme...
Selon moi une petite documentation plus les captures d'images rend toujours le code tres claire.
Trop de commentaire ( meme commenter if et else) n'a aucun sens : il salut trop le code
Dernièrement j'ai du réécrire en c++ des algos pour en faire une version finale, optimisée, parallélisée, avec une gestion d'erreur digne de ce nom. Ces algos sont relativement complexes, ont été 100 fois retouchés et j'ai du me contenter de la documentation du code pour découvrir :
- Quelle forme avait les données en entrées et en sortie
- Quel travail exact était fait.
Et franchement j'ai regretté de ne pas avoir eu un petit document explicatif à l'extérieur du code expliquant un peu dans les grandes lignes le pourquoi du comment; les auteurs se sont permis des optimisations en se basant sur des cas particuliers ou en ignorant des cas supposés ne jamais se produire et tout cela, le deviner en lisant du code et des commentaires c'est assez pénible.
Donc il m'a fallu plusieurs jours et quelques cheveux gris en plus pour mettre tout cela au clair dans ma tête, immédiatement après avoir réécrit l'algo je me suis empressé d'ouvrir un article wiki expliquant tout le déroulement du calcul à l'aide d'un exemple et d'explications. J'ai joint à ceci une documentation générée par doxydoc, en gros j'ai pris comme base ce que j'aurai moi-même souhaité pouvoir trouver avant de faire ce travail.
Je ne suis pas descendu au niveau code, j'ai simplement dit ce que ça faisait et comment, avec juste quelques lignes sur les librairies utilisées et les choix d'implémentations.
Toutefois c'est un boulot d'une journée par semaine de codage (20%), si j'ajoute les commentaires au propre et tout ça, je tombe surement pas loin des 24-30%.
A présent ce que je peux me poser comme question c'est : est-ce qu'au fil du temps ma doc a des chances de rester à jour? Ca je ne peux que l'espérer mais c'est effectivement préoccupant, on connaît tous les modifs/petites corrections vite faites et si la documentation n'est pas tenue à jour elle ne sert à rien ou pire, elle induit en erreur (Il suffit de voir certains projets open source).
La solution adoptée ici pour l'instant par mon patron, conscient de ce problème c'est de réserver un temps pour la gestion de document chaque semaine le vendredi après-midi, 2-3 heures pour se mettre autour d'une table dire ce que nous avons touché, puis ensuite mettre à jour note wiki en fonction de ça.
Personne, et moi le dernier.
En voyant ces chiffres, je m'interroge...
En gros quelle est la démarche par rapport à la personne à qui on demande de retravailler sur le projet, ou tout d'abord, est-ce que ce genre de chose est véritablement prévu et anticipé?
Est-il censé se débrouiller pour comprendre en regardant le code et en déduisant logiquement le fonctionnement général? Peux-tu donner en gros le contenu de la documentation externe pour un exemple d'une de tes application?
Pour une vue d'ensemble, on ne voit pas bien comment documenter dans le code.
Pour les algorithmes ou les explications de détail, il parait dangereux de commenter dans le code, car c'est susceptible de modification, sauf cas particuliers.
Pour une documentation de référence automatiquement à jour, difficile de faire mieux qu'un document généré, mais là encore si les commentaires ne sont pas disciplinés, cela peut-être contre-productif avec une référence ne correspondant pas (ou plus) à ses commentaires. De même, en cas de modification, se pose la question de la qualité de la revue de commentaires, ainsi que de la fusion avec les nouveautés.
Heureusement, il y a un type d'outil massivement utilisé dans l'industrie, qui n'a pas encore été cité dans cette discussion, et qui pourtant résout certaines des questions en suspens: comment assurer la compréhension du pourquoi tel code (et non pas seulement du comment l'utiliser, comme avec Doxygen) d'une part, et d'autre part comment assurer la cohérence entre l'état courant du code, qui dérive forcément, avec sa documentation initiale, qui forcément ne peut pas prendre en compte l'avenir lointain.
Je veux parler bien sûr du SCM utilisé pour le projet.
Pour prendre l'exemple de notre société, nous travaillons dans l'embarqué. Nous avons des lignes de code assez anciennes (> décennie) qui sont toujours très actives à la fois sur les toutes dernières versions, mais aussi sur les vieilles versions (c'est le bonheur mitigé de l'embarqué... la stabilité jusqu'au soutien du préhistorique).
Nous avons donc mis en place une politique de commentaire assez stricte: pas de commentaire algorithmique dans le code. Nommage extrêmement soigné, documentation du code avant tout fonctionnel, lié aux noms choisis, et évoluant seulement quand les noms des "classes" changent (ou pseudo-classes dans les langages qui ne les supportent pas, comme ceux de l'électroniques). Nous ne documentons pas les check-out, mais par contre les check-ins doivent impérativement être très précisément décrits, minimaux, très granulaires, et correspondre à au moins un "job" préalablement identifié (c'est un peu là que nous documentons les check-out, en fait). Le job ne peut qu'être suspendu ou clos, pas simplement cité pour référence.
De cette manière, quand nous reprenons un code vieux de 8 ans ayant passé par une dizaine de personnes dont 5 ont quitté la société, nous avons dans le code même une documentation de haut niveau, replaçant le contexte précisément. Puis nous pouvons, grâce aux outils du SCM, savoir quand telle ligne a été écrite, par qui (suivi SCM), pourquoi (suivi SCM + lien job), ce qui a été écrit en même temps, les fichiers affectés par le check-in ayant validé cette ligne, etc. Nous inspecter en une fraction de seconde les lignes que cette ligne remplace, et accéder au même niveau de détail pour les versions antérieures (ou postérieures, ou branchées dans une autre ligne de code, etc.). Ça, c'est pour la vue microscopique. Pour la vue macroscopique, elle est externe au code, ou dans le code mais très générale. Pour la vue de référence, elle est auto-générée (doxygen), à la volée si nous examinons une version disparue.
Ce qui est vraiment appréciable, c'est que le commentaire est à la fois extrêmement lié au code (on clique sur telle ligne, et le commentaire détaillé apparait), et complètement externe: on garde une très bonne lisibilité. Par rapport au genre doxygen, c'est lié à la version examinée.
Le cout de cette discipline est assez significatif (peut-être 10%), mais n'est pas seulement lié à la documentation, mais fait partie de notre effort général de qualité, en ce sens qu'il est intégré à notre utilisation d'un SCM.
Intéressant, mais ça demande visiblement d'être très pointu et très méthodique dans l'utilisation du source control non?
Vous utilisez team foundation à ce sujet?
Une documentation est produite dans le but de servir notamment à une personne nouvelle qui arriverait sur le projet.
La plupart des documentations que j'ai eu l'occasion de voir sont des généralités sur des couches n-tiers, je vois vraiment pas l'intérêt d'avoir un copier-coller d'un chapitre de bouquin, ou au contraire une plongée directe dans des détails où l'on se noit, c'est à dire que l'on ne sait même pas à quoi sert l'application
Bonjour,
Tout d'abord, il y a forcement plusieurs docs :
La doc de spec : soit elle est fournie par le client, soit elle est ecrite en interne, mais elle doit etre finie avant que la moindre ligne de code ne soit ecrite
La doc utilisateur, ou "Qu'est-ce que ca fait quand tu appuies la". La encore, rien a voir avec le code. Le fait que tu passes tes donnees dans un random avant de les trier via un algo quick-sort n'a rien a faire ici.
La doc fonctionnelle : elle peut etre generee a partir du code, mais doit absolument etre relue independamment du code pour voir si elle est limpide ou non.
Ensuite, en lisant la discussion, je suis surpris de constater que personne ne parle de departement documentation, et que toutes les docs ont l'air d'etre ecrites par les developpeurs. C'est la qu'est l'os a mon avis : il faut des gens payes par l'entreprise pour ecrire ces docs, et qui ne soient pas des developpeurs.
A chaque fois que j'ai vu un departement doc travailler avec les concepteurs et les developpeurs, la doc du projet etait bien faite.
Et ca presente aussi l'avantage de ne pas pouvoir sacrifier la doc au profit d'un raccourcissement des delais, ce qui est trop souvent fait.
Vous avez un bloqueur de publicités installé.
Le Club Developpez.com n'affiche que des publicités IT, discrètes et non intrusives.
Afin que nous puissions continuer à vous fournir gratuitement du contenu de qualité, merci de nous soutenir en désactivant votre bloqueur de publicités sur Developpez.com.
Répondre avec citation
Partager