Documentation informatique

[Geache]

Si vous deviez, ou si vous établissez une documentation informatique, quelle méthodologie utiliseriez-vous, ou utilisez-vous ?

Outre les commentaires dans les codes-sources bien sûr.

Et question à dix balles, existe-t-il une méthodologie standard, dans le domaine ?

Merci d'avance.

[Latinus]

Bonjour Geache,

Concernant la documentation de code, beaucoup se basent, voire utilisent, sur javadoc ou phpdoc.


Lat

[Geache]

Merci, Latinus, je vais explorer ces pistes.

[iubito]

Je confirme, javadoc et phpdoc. La syntaxe et le principe sont quasiment identiques, et c'est clair à lire même dans le code, et ça peut générer des pages HTML.

[Geache]

Il s'agit ici de documenter une application en VBA. Elle est développée en Access qui pilote une base sql de MS. Mais bon, c'est surtout le canevas, la structure, les passages obligés et ceux qui sont considérés comme des musts de la documentation qui m'intéressent. Qu'y met-on généralement ? Juste pour voir si la documentation que j'ai rassemblée s'inscrit dans ce que les informaticiens considèrent comme un standard.
Entre parenthèses, documenter une application écrite par d'autres en commençant dix ans après la première ligne codée, je ne vous le souhaite pas.

[iubito]

ça dépend un peu...

- si une personne doit retoucher au code un jour... il faut dans l'idéal tout documenter, dans la pratique, au moins dire chaque fonction ce qu'elle fait (ce qu'elle attend en entrée, ce qu'elle retourne).
mais aussi, à l'intérieur de la fonction, si le code est complexe et n'est pas naturellement compréhensible, expliquer pourquoi on fait ça ou ça.

- si le destinataire est une personne qui ne va pas toucher aux sources, mais appeler des fonctions de ton programme, alors il faut la même chose (ce que la fonction attend en entrée, ce qu'elle retourne), mais faut aussi cacher les fonctions de la "sauce interne" du programme auxquelles un informaticien extérieur ne doit pas accéder. (en java et php? c'est le mot clef "private" defant la fonction.

[Geache]

Bah, ici, la personne sensée retoucher au code, c'est moi. Mais vu que je ne suis pas éternel...