Discussion :

[_skip]

Bonjour,

Je crée ce topic dans le but de discuter non pas de l'utilité d'une documentation, à cela tout le monde serait à peu près d'accord pour répondre que c'est indispensable, mais de sa forme.

La standardisation du format des commentaires dans le code permet leur extraction automatique ainsi que la compilation automatique d'un document plus ou moins bien fichu sous divers format (HTML, Latex, Chm, XML et j'en passe), parfois accompagné de diagrammes en tout genre. Je pense à des outils tels que javadoc, ndoc, phpdocumentor, doxygen.

Il me semble que ces documentations autogénérées, bien qu'elles soient incontestablement pratiques restent souvent peu bavardes sur les raisons des choix de designs et d'implémentation, voir sur l'aspect fonctionnel en temps que tel (en gros que fait le programme et quelle est la réflexion à sa base?)

J'ai l'impression que la documentation en entreprise (pour celle que je connais, dont certaines sont pourtant de tailles conséquentes) est souvent un point assez négligé, et que les docs générées y sont parfois utilisées pour se donner bonne conscience en se disant "ok on bosse correctement, on a une doc".
Je ne connais pas beaucoup de programmeurs qui ont tendance à écrire des pavés de 200 lignes au-dessus des classes pour décrire leur fonctionnalité et pourquoi elles sont ainsi et pas autrement.

On sait plus où moins que le temps destiné à la doc est souvent le premier dans lequel on taille sitôt que la pression d'un délai de livraison se fait sentir. C'est normal et assez humain, cependant la question reste toujours la même : Comment faire pour que ce soit bien, sans être superflu et chronophage?

De votre côté dans votre entreprise, qu'utilisez-vous au sein de l'équipe? Quel genre de documentation produisez-vous?

- Un full UML?
- Une documentation autogénérée à partir du code ?
- Un wiki collaboratif ?
- Un manuel développeur ?
- Un manuel utilisateur aussi ?
- Un document contenant les spécifications? le pourquoi de vos choix et la raison pour laquelle vous avez écarté les autres possibilités?

Et enfin quel est approximativement le pourcentage de temps de travail accordé à la documentation au sein de votre structure?

[gl]

Il me semble que ces documentations autogénérées, bien qu'elles soient incontestablement pratiques restent souvent peu bavardes sur les raisons des choix de designs et d'implémentation, voir sur l'aspect fonctionnel en temps que tel (en gros que fait le programme et quelle est la réflexion à sa base?)

De mon point de vu, ce n'est pas le rôle de ce type de documentation générée.

Le rôle des commentaires et donc de la documentation produite à partir de ceux ci est de décrire des fonctions et leur interface (en gros que font-elles et comment les utiliser).

La description fonctionnelle d'une application et les choix de design ou d'implémentation n'ont rien à faire dans ce genre de documentation.
D'autant plus que ce sont des points qui sont traités dans des phases largement en amont de la réalisation et qui sont donc documentés bien avant l'écriture du code et des commentaires et donc de la génération de documentation depuis les commentaires.

[Tommy31]

Je vais relater mon expérience.

* Un full UML?

Déjà fait pour la production de document de spécification logicielle, de conception et d'architecture. Le point fort est d'avoir une document cohérent. Avant, on rédigeait un document et on insérait des captures d'écran de quelques modèles UML, il y avait parfois inconsistance entre les deux.

Il est possible par cette démarche d'aller encore plus loin sur du MDA, mais personnellement, à ce niveau, je ne pense pas que cela permette un gain de temps.

- Une documentation autogénérée à partir du code ?

Oui, avec un outil comme javadoc customisé, il est possible de ressortir un document de conception pas trop mal, pour peu que le code soit enrichi des commentaires adéquats.

Ainsi il est possible de décrire les interactions d'une méthode ou d'une classe avec un diagramme de séquence textuel et d'en générer une représentation graphique dans la documentation. (des outils comme http://www.websequencediagrams.com/ font ça bien).

Il est également possible de rajouter des annotations pour faire apparaître les différents design pattern mis en jeu, ou simplement la nature des classes (entités, dao, service...).

Les exigences peuvent aussi être exprimées dans le code, puis exhibées dans le document assorti d'une matrice de couverture. Mais, je ne suis jamais allé aussi loin.

- Un wiki collaboratif ?

Déjà utilisé, mais uniquement pour des documents de spécification ou des manuels utilisateurs (ou d'exploitation). Le pb d'un wiki c'est la gestion des images.

Et enfin quel est approximativement le pourcentage de temps de travail accordé à la documentation au sein de votre structure?

Difficile à évaluer, mais ca me paraît assez élevé. Je dirais bien 30%.

[el_slapper]

(.../...)
La description fonctionnelle d'une application et les choix de design ou d'implémentation n'ont rien à faire dans ce genre de documentation.
D'autant plus que ce sont des points qui sont traités dans des phases largement en amont de la réalisation et qui sont donc documentés bien avant l'écriture du code et des commentaires et donc de la génération de documentation depuis les commentaires.

Mais dans les commentaires?

Mon expérience de maintenance et de refontes d'applications plus vieilles que moi me pousse à penser que le code est la seule documentation qui survit à travers les âges. Donc, il doit expliquer. Expliquer pourquoi on fait cette bidouille là. Parce que 36 ans plus tard(authentique), le jeunot(de 33 ans, mais peu importe) qui devra reprendre l'application n'aura pas à passer une semaine à questionner toute la boite dans l'espoir de retrouver un début d'indice sur le pourquoi de certains choix.

Cela ne signifie pas que la doc soit inutile. Dès que l'architecture est un poil complexe, un court regard sur un schéma est plus efficace qu'une longue analyse du code. Mais ne pas penser au jour ou la doc sera perdu est réellement dommage. Parce qu'elle le sera peut-être avant que le code ne soit obsolète. Cela arrive souvent. Quasiment toujours quand le code vit plus de 10 ans(pas le cas le plus fréquent, mais ça arrive).

Après, sur le comment, je passe trop souvent d'une mission à l'autre pour donner des détails précis. Je ne pense pas que telle méthode de documentation soit bonne ou mauvaise, juste qu'elle est ou non adaptée à telle situation.

[Invité]

Pour moi, la doc générée à partir des commentaires, ce n'est pas de la doc, mais des commentaires : c'est à dire quelque chose destiné aux futurs mainteneurs du code. A mon avis, l'idéal est que le commentaire soit le code (les commentaires écrits ou générés ont la fâcheuse tendance à ne pas suivre les évolutions et les refontes, et on se trouve dans la situation où la "doc" ne décrit pas le code).

Mais cela ne doit pas se substituer à une documentation, utilisateur ou fonctionnelle.

Une documentation utilisateur, il en faut toujours une. Une fois de plus, idéalement, le logiciel est assez intuitif pour qu'elle puisse être minimaliste, mais elle reste nécessaire.

C'est un peu ca le paradoxe, d'ailleurs. Un bon code n'a pas besoin de beaucoup de commentaire, un bon programme n'a pas besoin de beaucoup de doc. Donc, si on doit passer beaucoup de temps à écrire commentaires et doc, ce temps serait mieux investi en amélioration du code et du programme.

Francois

[souviron34]

nous avons (longuement) débattu de ce sujet dans un autre thread ("Qu'est-ce qu'un code propre ?" ou bien "Les bonnes pratques", je ne me souviens plus).

Pour moi effectivement la seule vraie doc restante (et normalement la plus à jour car la plus dynamique) est le code..

Quitte à jouer les redondances à court terme, je pense qu'effectivement le plus sage est de mettre dans le code tout commentaire un peu pointu, du style pourquoi cette constante ? pourquoi cet algo (à moins que l'on insère une référence sur un bouquin précis ou une revue (internationale. Dont on sait qu'elle figurera dans 20 ans dans les archives de bibliothèques, et pas "la Lettre de Toto de Trifouillis-Les-Oies") précise, quelle est l'origine (par exemple d'un expert) de cette règle empirique , etc etc..

Et par exemple, dans le cadre algorithmique, un résumé succint en entête de l'algo si il est un tantinet complexe..

[Invité]

Et par exemple, dans le cadre algorithmique, un résumé succint en entête de l'algo si il est un tantinet complexe..

Et ça, seulement si on est certain que l'algo ne changera JAMAIS ! Parce que des commentaires décrivant un autre algo que celui utilisé (parce que le singe habillé qui a fait la dernière mise à jour n'a pas jugé bon de documenter une "petite modif", ou ce qu'il considére comme une optimisation) c'est non seulement dangereux, mais aussi banal !

Pour revenir à la doc, c'est la raison pour laquelle je me méfie (voire j'évite) les specifications fonctionnelles, ou les manuels du développeur. Ils tendent à n'être à jour qu'au début du cycle de vie du programme, quand on n'en a pas besoin...

Francois

[souviron34]

Et ça, seulement si on est certain que l'algo ne changera JAMAIS ! Parce que des commentaires décrivant un autre algo que celui utilisé (parce que le singe habillé qui a fait la dernière mise à jour n'a pas jugé bon de documenter une "petite modif", ou ce qu'il considére comme une optimisation) c'est non seulement dangereux, mais aussi banal !

je ne sais pas..

Les codes que j'ai pondu ou sur lesquels j'ai travaillé indiquaient tous, dans les commentaires, les évolutions des algos...

Donc je dirais, non, pas si on est certain que l'algo ne changera jamais.

Au contraire ...

Simplement une certaine discipline minimale suppose justement de garder pour la postérité les modifs ...



Mais je suppose que maintenant avec justement les outils automatiques et les IDE qui font tout et les langages ne survivant pas 5 ans on oublie d'enseigner que ceci est une des bases fondamentales de notre travail...

[Mac LAK]

A titre personnel, j'applique en général la méthode suivante :

• Le document de spécification est au format usuel (=Word).
• Le document de conception général est au format Word lui aussi. Il explique les raisons de tel ou tel choix technologique, par rapport à l'existant et/ou aux contraintes budgétaires.
• La documentation générée va contenir :
  • La documentation du code (API, implémentation, etc.) bien entendu.
  • Le détail technique de l'implémentation spécifique : par exemple, c'est là que j'indique que l'on utilise la librairie Machin pour la fonction Bidule. La raison de l'existence de la fonction Bidule est décrite dans le document précédent.
  • Une partie manuel d'utilisation : documentation des interfaces publiques exclusivement, et élimination des parties privées.
  • Une partie d'explications sur la prise en main, les ressources, les formats de données, les diagrammes de séquences et état/transition, etc.
  • Une partie, enfin, est consacrée aux tests (automatiques ou non) associés au système.

Côté "comment ?", j'utilise en général Doxygen pour générer les docs à partir du 3ème point. J'ai en général plusieurs jeux de fichiers de configuration me servant à générer :

• Une documentation développeur axée "maintenance/évolution".
• Une documentation développeur axée "intégration du module dans une autre application"
• Un manuel utilisateur pur et dur (pour les exécutables).
• Un manuel de test/maintenance/configuration.

Bien sûr, en fonction de la complexité du projet, ces documents peuvent ne pas exister et/ou correspondre à une page de doc "pure" dans le manuel général.

A noter que je fais en général un usage intensif des éléments suivants :

• Génération de schémas (pour rendre la doc plus parlante) via dot, mscgen ou, plus rarement, outils tiers (sortie en bitmap bien sûr).
• Inclusion dans la documentation des jeux de test pour fournir un exemple.
• Pour l'utilisation par code, utilisation de l'analyseur lexical de Doxygen pour récupérer les exemples de code directement depuis les programmes d'autotest.
• Documentation des évolutions, régressions, cassages lors des évolutions (balises \since, \deprecated, etc.).
• Documentation des pré/post conditions des fonctions critiques (j'avoue zapper un peu pour les fonctions-bateau et/ou ayant leur propre gestion d'erreurs).
• Classement des éléments documentés dans des groupes possédant leur propre documentation "verbeuse".

En général, le résultat produit est plus que correct, et l'on peut même se payer le luxe de respecter les chartes graphiques de l'entreprise et les éléments liés au respect de l'ISO-9001...

[souviron34]

mais tu n'as pas répondu à la question du thread

[_skip]

Difficile à évaluer, mais ca me paraît assez élevé. Je dirais bien 30%.

Oui je me suis surpris à penser que finalement il ne faudrait pas beaucoup moins. Tout en sachant que c'est très difficile de s'y tenir si nos supérieurs ou les autres structures de l'entreprise ne se montrent pas compréhensifs.

Lorsqu'on ne peut pas garantir ce temps tout au long du cycle c'est là je pense qu'on risque de se retrouver avec des documents anciens qui ne correspondent plus vraiment à la réalité.

[Mac LAK]

mais tu n'as pas répondu à la question du thread

Ben si : _skip demandait "qu'utilisez-vous au sein de l'équipe? Quel genre de documentation produisez-vous?"...

[Mac LAK]

Arf, raté celle-là : "quel est approximativement le pourcentage de temps de travail accordé à la documentation au sein de votre structure?"...

En gros : moi, approximativement 25 à 35% en fonction de la complexité du projet. Pour d'autres, cela va de zéro à 10% max, mais je ne peux pas dire ce que je pense réellement de l'utilité de leurs documents, ça serait censuré.

[souviron34]

mais je ne peux pas dire ce que je pense réellement de l'utilité de leurs documents, ça serait censuré.

ce qui était quand même un peu le titre du thread....


Ce que je suppose avec ce que tu dis là, c'est que, comme moi et comme toute personne ayant pas mal baroudé sur d'assez gros (voire gros) projets, la doc telle qu'elle est faite en général , bien qu'utile à certains stades, est en gros relativement mal utilisée (et souvent également mal "faite", au sens de "pas forcément au bon endroit ou ne documentant pas forcément les choses vrament utiles)...

D'où la question originale, et ma réponse


Ce n'est pas incmpatible d'avoir une bonne doc et du code bien commenté, mais l'un dans l'autre il vaut mieux un code bien documenté (si la structure est claire et logique) que 20 000 pages de docs..

[Mac LAK]

Ce que je suppose avec ce que tu dis là, c'est que, comme moi et comme toute personne ayant pas mal baroudé sur d'assez gros (voire gros) projets, la doc telle qu'elle est faite en général , bien qu'utile à certains stades, est en gros relativement mal utilisée (et souvent également mal "faite", au sens de "pas forcément au bon endroit ou ne documentant pas forcément les choses vrament utiles)...

C'est plutôt que la doc devient plus nuisible qu'autre chose. De façon non-exhaustive :

• Rédigée dans un français très moyen, avec fautes d'orthographe, grammaire, typographie, etc. : c'est un torchon.
  On passe pour des guignols face au client (doc crade = programme crade = plein la tête au moindre bug).
• Méconnaissance flagrante de l'outil utilisé (ex : Word), par exemple ignorer l'utilisation correcte des styles ou des outils intégrés.
  Que penser d'un développeur, et surtout de la qualité de son code, s'il est capable d'utiliser (mal) un outil sans même avoir la curiosité de lire la doc et/ou de demander conseil ??
• Incohérence entre la documentation papier et le code produit (dans le cas de documentation non-issue du code).
  No comment : le premier qui reprends le truc a gagné une migraine gratuite.
• Absence d'évolution des documents, ou absence de documents terminaux (genre document de validation).
  No comment là aussi : au premier audit (ISO ou du client), c'est la crucifixion en règle.
• Non respect de la langue requise : doc en anglais plus qu'approximatif, et code source en franglais illisible genre "ReadFichier" d'un côté, et "LectureFile" dans l'autre module...
  Là encore, en cas d'audit, c'est la mort. Pour trouver le nom d'une fonction dans la doc, c'est la roulette russe au lieu d'être simplement logique.
• Etc.

Ce n'est pas incmpatible d'avoir une bonne doc et du code bien commenté, mais l'un dans l'autre il vaut mieux un code bien documenté (si la structure est claire et logique) que 20 000 pages de docs..

Je dirais plutôt qu'un code bien commenté et une documentation issue du code font partie intégrante d'une bonne documentation globale.

Les documents "papier" doivent exister, bien sûr, ne serait-ce que pour les éléments contractuels et/ou les généralités n'évoluant quasiment jamais (d'où les documents de spécification et de conception générale au format Word pour ma part).
Tout le reste doit être généré dans la mesure du possible, et bien sûr relu et révisé.

[souviron34]

C'est plutôt que la doc devient plus nuisible qu'autre chose.

Comme je l'avais mentionné dans la partie du thread mentionné plus haut, je suis d'accord avec toi..

Et en particulier sur :

.

• Absence d'évolution des documents, ou absence de documents terminaux (genre document de validation).
  No comment là aussi : au premier audit (ISO ou du client), c'est la crucifixion en règle.

C'est pour ça que ça me fait pas mal rigoler....

Surtout quand tu ajoutes les audit... et les normes...

Car en fait, ce que les audits et normes vérifient, c'est justement que la doc (du processus, et du cycle) sont bien là... Mais ni que le code correspond à la doc (ou inversement), ni que cela fait ce que cela devait faire....


Et du coup les équipes de dev passent un temps absolument fou à faire de la doc (proportionnellement)... pour une grande part relativement inutile, ou tout au moins inexploitable réellement...


Je ne sais pas pour ton expérience, mais dans la mienne j'ai pu constater que les docs en général, et encore plus les docs "normées", sont à 80% une perte de temps (pour les très gros projets), à cause de ce genre de dérives...

Que ce soit les specs, les analyses générales, ou même détaillées, au bout de 2 ans déjà elles ne sont plus à jour... Alors au bout de 10 ou 15... N'en parlons même pas....

De plus, quel dev (ou chef de projet) va lire 25 000 pages (ou même 1000) avant de regarder la structure du soft , si les noms des répertoires et fichiers sont compréhensibles, et fureter un peu ?

Comme tu le dis :

.
Je dirais plutôt qu'un code bien commenté et une documentation issue du code font partie intégrante d'une bonne documentation globale.

Les documents "papier" doivent exister, bien sûr, ne serait-ce que pour les éléments contractuels et/ou les généralités n'évoluant quasiment jamais (d'où les documents de spécification et de conception générale au format Word pour ma part).

Mais croire (ou affirmer encore pire) que faire de la doc "normée" est la solution à la pérennité et à un développement correct est une invention de "wishfull thinking"...

[Mac LAK]

Mais croire (ou affirmer encore pire) que faire de la doc "normée" est la solution à la pérennité et à un développement correct est une invention de "wishfull thinking"...

Pour être plus précis, tout dépend de l'auditeur : si c'est l'organisme ISO, c'est en général non-vu.
Quand c'est le client qui audite, notamment les militaires, c'est une autre paire de manches... C'est encore pire quand c'est l'audit par rapport à une norme de sécurité / sûreté de fonctionnement : là, c'est le tir direct dans la tête du responsable projet, qui en général se vexe et envoie les shrapnels sur l'équipe de développement...

[Nebulix]

Je suis un peu surpris que personne n'ait posé la question de savoir à qui était destinée la documentation.
De fait, la rétention d'information semble la pratique la plus généralisée.
Est-ce mieux en interne ?

[souviron34]

Je suis un peu surpris que personne n'ait posé la question de savoir à qui était destinée la documentation.
De fait, la rétention d'information semble la pratique la plus généralisée.
Est-ce mieux en interne ?

vu le titre du thread on ne parle pas de la documentation en général, mais la documentation liée au code...

[Nebulix]

Le code est destiné à une machine, la documentation à un humain : ils doivent se séparer quelque part.( il y a même des outils pour ça)
Dans tous les cas ( code ou pas code) je suis persuadé que se poser la question : "qui lira cette doc, et pourquoi ?" est essentiel pour rédiger quelque chose d'utile.
Celà me parait relever du simple bon sens, mais n'est pas tellement répandu.