Discussion :

[ArnaudVS]

Bonjour à tous,

J'ai maintenant quelques années d'expérience en développement (uniquement C et C++ pour ma part) et jusqu'à présent, je n'ai encore pas trouvé LE bon outil pour documenter convenablement du code.
Prenons l'exemple de Doxygen, qui reste dans les tops des recherches qu'on peut faire à ce sujet.

C'est effectivement un outil puissant, mais il comporte de nombreuses faiblesses. Notamment, sa syntaxe un peu vieillotte mais surtout, l'impossibilité d'être averti lorsqu'une fonction a changé de corps ou de paramètres.
Très rapidement, on a donc une doc qui n'a plus rien à voir avec le véritable code qui a continué d'évoluer.

J'en viens à me poser quelques questions et j'aimerais votre avis:

1- D'abord, peut-être que je ne sais tout simplement pas utiliser Doxygen, et qu'il est possible d'avertir quand une modification dans le code n'a pas été documentée.
2- Peut-être que mon point de vue sur l'utilisation de ce genre d'outil est faux. Pour moi, il est important de documenter le code dès le début du projet. Mais finalement, il est peut-être plus judicieux de ne documenter qu'une fois le projet terminé ? (J'en doute)
3- Doxygen n'est peut-être finalement pas l'outil idéal, et il existe aujourd'hui d'autres outils mieux conçus. Dans ce cas, n'hésitez pas à donner vos favoris avec les + et les -

En bref, quelle approche avez-vous vis-à-vis de la documentation de code ?

Je vous remercie d'avance!

Arnaud

[Pyramidev]

Bonjour,

Doxygen s'est imposé comme standard de facto pour la documentation en C++. Du coup, le développement d'outils autour de la documentation en C++ se fait et se fera majoritairement autour de Doxygen.

Par exemple, voici un extrait de la documentation de Clang :

Clang parses Doxygen and non-Doxygen style documentation comments and attaches them to the appropriate declaration nodes. By default, it only parses Doxygen-style comments and ignores ordinary comments starting with // and /*.

-Wdocumentation

Emit warnings about use of documentation comments. This warning group is off by default.

This includes checking that \param commands name parameters that actually present in the function signature, checking that \returns is used only on functions that actually return a value etc.

-Wno-documentation-unknown-command

Don’t warn when encountering an unknown Doxygen command.

Donc, en C++, Doxygen me semble être le choix le plus raisonnable.

2- Peut-être que mon point de vue sur l'utilisation de ce genre d'outil est faux. Pour moi, il est important de documenter le code dès le début du projet. Mais finalement, il est peut-être plus judicieux de ne documenter qu'une fois le projet terminé ? (J'en doute)

En bref, quelle approche avez-vous vis-à-vis de la documentation de code ?

La bonne quantité de documentation à écrire dépend du contexte.
Si on conçoit une API stable qui a beaucoup d'utilisateurs, le cas le plus flagrant étant celui d'une bibliothèque standard d'un langage, alors il faut écrire beaucoup de doc de telle sorte que les utilisateurs n'aient pas besoin d'aller plonger dans le code source pour avoir les informations qu'ils cherchent.
Dans les projets en entreprise, par contre, on se retrouve souvent dans le cas où le code d'un projet n'est utilisé que par les personnes du projet. Dans ce genre de cas, il vaut mieux bannir les commentaires qui ne font que répéter le code.
Il y a aussi des situations intermédiaires, par exemple quand on écrit un code commun à plusieurs projets d'une même entreprise.

Dans quel contexte travailles-tu ?

[ArnaudVS]

Bonjour Pyramidev et merci pour ta réponse.


Mon contexte de travail: nous avons développé un petit projet sans grande ambition à 2. Puis de fil en aiguille ce projet a intéressé de plus en plus de monde à tel point qu'aujourd'hui, nous manquons de temps pour réaliser toutes les fonctionnalités attendues.
D'autres développeurs vont donc nous aider en reprenant des parties du projet, et l'état de la doc Doxygen actuelle est tout simplement... misérable.
Comme de toute évidence il faudra tout reprendre pour la mise à jour des définitions, c'était l'occasion de passer à autre chose que Doxygen mais puisqu'en 2020, c'est encore la meilleure alternative...

[Trehinos]

Bonjour,

Professionnellement, je bosse plutôt sur du PHP mais j'aime bien programmer en C++ sur mon temps libre, revenir à mes premières amours.
Dans les deux cas j'utilise les docbloc comments (/** */). Je crois que c'est ce que fais Doxygen aussi, mais même sans, les IDE savent très bien parser les commentaires spéciaux pour fournir une documentation à la volée.

Selon moi, c'est ça le meilleur outil. Mais ça impose une certaine rigueur : à chaque modification de code, il faut changer la documentation correspondante. Selon les IDE (c'est mon cas sur PHPStorm), l'éditeur peut prévenir s'il détecte une incohérence (type de retour doc/code différents, paramètres différents, etc).
Si la documentation n'est pas modifiée en même temps que le bloc de code qu'elle documente, c'est que la modification est incomplète et elle ne devrait pas être validée (revue de code en travail collaboratif).