Navigation

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

Langages de programmation Discussion :

Selon vous, quel est le meilleur outil de documentation ?


Sujet :

Langages de programmation

  1. #1
    Candidat au Club
    Homme Profil pro
    Ingénieur développement logiciels
    Inscrit en
    octobre 2018
    Messages
    4
    Détails du profil
    Informations personnelles :
    Sexe : Homme
    Localisation : France, Rhône (Rhône Alpes)

    Informations professionnelles :
    Activité : Ingénieur développement logiciels
    Secteur : Transports

    Informations forums :
    Inscription : octobre 2018
    Messages : 4
    Points : 3
    Points
    3
    Par défaut Selon vous, quel est le meilleur outil de documentation ?
    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

  2. #2
    Expert confirmé
    Avatar de Pyramidev
    Homme Profil pro
    Développeur
    Inscrit en
    avril 2016
    Messages
    1 049
    Détails du profil
    Informations personnelles :
    Sexe : Homme
    Localisation : France, Val de Marne (Île de France)

    Informations professionnelles :
    Activité : Développeur

    Informations forums :
    Inscription : avril 2016
    Messages : 1 049
    Points : 4 490
    Points
    4 490
    Par défaut
    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.

    Citation Envoyé par ArnaudVS Voir le message
    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)
    Citation Envoyé par ArnaudVS Voir le message
    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 ?

  3. #3
    Candidat au Club
    Homme Profil pro
    Ingénieur développement logiciels
    Inscrit en
    octobre 2018
    Messages
    4
    Détails du profil
    Informations personnelles :
    Sexe : Homme
    Localisation : France, Rhône (Rhône Alpes)

    Informations professionnelles :
    Activité : Ingénieur développement logiciels
    Secteur : Transports

    Informations forums :
    Inscription : octobre 2018
    Messages : 4
    Points : 3
    Points
    3
    Par défaut
    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...

  4. #4
    Membre régulier Avatar de Trehinos
    Homme Profil pro
    Analyste développeur PHP
    Inscrit en
    novembre 2012
    Messages
    57
    Détails du profil
    Informations personnelles :
    Sexe : Homme
    Âge : 29
    Localisation : France, Hérault (Languedoc Roussillon)

    Informations professionnelles :
    Activité : Analyste développeur PHP
    Secteur : Distribution

    Informations forums :
    Inscription : novembre 2012
    Messages : 57
    Points : 119
    Points
    119
    Par défaut
    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).

Discussions similaires

  1. Réponses: 65
    Dernier message: 30/09/2019, 19h45
  2. Quel est le meilleur outil de profilage d'une appli J2EE ?
    Par Faiche dans le forum Tests et Performance
    Réponses: 6
    Dernier message: 19/04/2011, 14h55
  3. Test, quel est le meilleur outil ?
    Par rambc dans le forum Général Python
    Réponses: 2
    Dernier message: 28/09/2010, 21h27
  4. Réponses: 7
    Dernier message: 20/05/2010, 18h04

Partager

Partager
  • Envoyer la discussion sur Viadeo
  • Envoyer la discussion sur Twitter
  • Envoyer la discussion sur Google
  • Envoyer la discussion sur Facebook
  • Envoyer la discussion sur Digg
  • Envoyer la discussion sur Delicious
  • Envoyer la discussion sur MySpace
  • Envoyer la discussion sur Yahoo