Doxygen, trop lourd pour maintenir? [fermé]

StackOverflow https://stackoverflow.com/questions/2407976

Question

Je suis actuellement à l'aide commence doxygen pour documenter mon code source. Je remarque que la syntaxe est très lourd, chaque fois que je modifie le code source, je dois aussi changer le commentaire et j'ai vraiment l'impression de passer trop de temps modifier le commentaire pour chaque changement que je fais dans le code source.

Avez-vous des conseils pour documenter mon code source efficace?

Est-ce un éditeur (ou plug-in pour l'éditeur existant) pour doxygen effectuer les opérations suivantes existent?

  • suivre automatiquement le code désynchronisé / commentaire et avertir le programmeur à ce sujet.
  • ajouter automatiquement le format doxygen de commentaire (modèle avec le nom de paramètre dans ce par exemple) dans le code source (modèle) pour chaque nouvel élément

PS:. Je travaille sur un projet C / C ++

Était-ce utile?

La solution

Est-ce la syntaxe Doxygen vous trouvez difficile? Ou est-ce le fait que vous devez commenter toutes les fonctions maintenant.

Si c'est le premier cas, il peut y avoir un autre outil qui convient le mieux à votre style de codage. Gardez à l'esprit que Doxygen prend en charge les styles commentent multiples, afin d'expérimenter jusqu'à ce que vous trouviez celui que vous aimez.

Si c'est ce dernier, puis endurer. En tant que bonne pratique de programmation, toutes les fonctions orientées public devrait avoir un en-tête de commentaire qui explique:

  1. Qu'est-ce que la fonction fait
  2. Les paramètres
  3. Les codes de retour
  4. Les principaux avertissements / limites sur la fonction.

Ceci est vrai quel que soit l'outil de documentation que vous utilisez.

Mon grand conseil: Évitez la tentation de trop commenter. Décrivez ce que vous avez besoin, et pas plus. Doxygen vous donne beaucoup de balises, mais vous ne devez pas les utiliser tous.

  • Vous ne toujours pas besoin d'un @brief et une description détaillée.
  • Vous n'avez pas besoin de mettre le nom de la fonction dans les commentaires.
  • Vous n'avez pas besoin de commenter le prototype de la fonction et la mise en œuvre.
  • Vous n'avez pas besoin du nom de fichier en haut de chaque fichier.
  • Vous n'avez pas besoin d'une histoire de version dans les commentaires. (Vous utilisez un outil de contrôle de version, non?)
  • Vous n'avez pas besoin « date de dernière modification » ou similaire.

Quant à votre question: Doxygen a quelques options de configuration pour déclencher des alertes lorsque les commentaires ne correspondent pas au code. Vous pouvez intégrer dans votre processus de construction, et analyser la sortie Doxygen pour tous les avertissements. C'est la meilleure façon que j'ai trouvé pour attraper les écarts dans le code vs commentaires.

Autres conseils

Il y a quelque chose de mal au sérieux au sujet de la façon dont vous utilisez les commentaires, ou comment vous développez.

commentaires Doxygen sont utilisés pour la documentation externe / interne sur les interfaces. Si vos interfaces changent extrêmement rapide, alors vous devriez probablement vous asseoir et de réfléchir à la mise en page de l'architecture d'abord.

Si vous utilisez doxygen pour documenter le flux interne des fonctions, alors vous devriez repenser cette approche peut-être (et même alors, ces commentaires ne devraient pas changer beaucoup). Lorsque vous avez une fonction qui calcule une valeur alors un commentaire /// Calculating xy using the abc algorithm est certainement quelque chose qui ne devrait pas changer chaque jour.

Je sens que vous obtenez ce que vous mettez en commentaires, à 5 minutes commentent un puits de classe sera en 3 mois alors que doit être changé la classe par une personne autre que l'auteur original (parfois même par l'auteur original) prendra beaucoup moins de temps pour se familiariser avec.

Je seconde le soutien de la documentation mentionnée par David, dans Eclipse lorsque vous Refactor les noms de paramètres, il renomme le paramètre dans votre section docs par exemple. Je ne suis pas sûr que je veux faire autre chose automatiquement pour être honnête.

« à chaque fois que je modifie le code source, je dois aussi changer le commentaire » Peut-être vous documenter trop. Vous ne devriez avoir à modifier la documentation d'une fonction si le changement à elle vous oblige à changer chaque appelant d'une certaine façon (ou si le changement ne fait, au moins vérifier pour vous assurer qu'ils ne dépendaient pas sur le comportement obsolète), de si vous introduisez de nouvelles fonctionnalités qu'un nouvel appelant compter. Donc, en théorie, il ne devrait pas être une surcharge énorme. De petits changements, comme les optimisations et corrections de bugs dans la fonction, ne sont généralement pas besoin documentant.

Cela dépend vraiment de la quantité d'informations que vous mettez dans votre documentation.

Mes fonctions généralement plus petite maintenant en raison de tests unitaires et donc la documentation est en conséquence faible. De même, lorsque la documentation de la classe elle-même, je l'ai toujours un petit bout de code pour montrer comment la classe est censé utiliser. Je trouve ce sont les plus difficiles à maintenir, mais vaut la peine si vous ne recevez pas les juniors écoute vous demandant comment ils utilisent la classe.

Conseils:

  • documenter uniquement vos interfaces publiques.
  • Ne faites peu de documents sur ce que la fonction.
  • Essayez d'utiliser un éditeur qui a le soutien (la plupart) ou a un plug-in.

Vous serez heureux quand vous venez d'éditer votre code dans le temps de 6 mois ...

Utiliser un commentaire non documentant pour de nouvelles fonctionnalités et au début des étapes de votre code. Lorsque vous trouvez que votre code est prêt à publier, vous pouvez mettre à jour docs. Evitez également la répétition des noms d'argument ou de fonction.

Pas exactement ce que vous cherchez, mais cette plug-in Vim peut générer stub Doxygen au-dessus de vos définitions. Il fonctionne assez bien.

Jugez vous-même si le style ci-dessous correspond à vos besoins. Il est tho C-affines, mais vous pouvez peut-être tirer assez de pour vos extrémités. 

///\file

/// Brief description goes here
bool /// @retval 0 This is somewhat inconsistent. \n Doxygen allows several retval-descriptions but 
     /// @retval 1 will not do so for parameters. (see below)
PLL_start( 
   unsigned char busywait, ///< 0: Comment parameters w/o repeating them anywhere. If you delete this param, the
                           ///     comment will go also. \n
                           /// 1: Unluckily, to structure the input ranges, one has to use formatting commands like \\n \n
                           /// 2-32767: whatever
   int param)              ///< 0: crash \n
                           ///  1: boom \n
                           ///  2: bang!
{
   /**
    * Here goes the long explanation. If this changes frequently, you have other more grave problems than 
    * documentation. NO DOCUMENTATION OF PARAMETERS OR RETURN VALUES HERE! REDUNDANCY IS VICIOUS!
    * - Explain in list form.
    * - It really helps the maintainer to grok the code faster.
    *
    *@attention Explain misuses which aren't caught at runtime.
    *
    *@pre Context:
    * - This function expects only a small stack ...
    * - The call is either blocking or non-blocking. No access to global data. 
    *
    *@post The Foobar Interrupt is enabled. Used system resources:
    *    - FOO registers 
    *    - BAR interrupts
    */
    /**@post This is another postcondition. */
}

Dans mon expérience de logiciels professionnels, chaque fois qu'un fichier source est modifié, un commentaire doit être saisi décrire le changement. Ces commentaires de changement ne sont généralement pas dans les zones de commentaires Doxygen (sauf si des modifications sont apportées à une interface).

Je vous suggère fortement vous faire commenter votre code une habitude. Non seulement est-ce bon pour quand d'autres personnes doivent maintenir ou vous aider avec votre code, mais il aide quand vous abandonner un fichier source pendant un certain temps (par exemple lorsque la direction vous dit de passer des projets). J'ai trouvé que l'écriture des commentaires code je me aide à mieux comprendre les algorithmes.

En plus de Doxygen Je pense que vous devriez jeter un oeil à Rocket .

Il fait des documents ce qui se passe « à l'intérieur » de vos méthodes par la pêche au chalut dans le code réel et des commentaires qu'ils contiennent -. Donc pas seulement se limiter à les en-têtes de commentaire de la fonction, ce qui peut sortir de ce jour avec ce que le contenu de la fonction sont en fait

Il vous fournira automatiquement visualisations organigramme et pseudocode de contenu de votre méthode comme une forme de documentation.

Utilisez les points forts de Doxygen - il va générer des descriptions de classe et de méthode sans vous ajouter des commentaires. (Tout simplement pas par défaut - Pour définir EXTRACT_ALL = YES)

Je ne documente tous les paramètres parce que je pense que leurs noms devraient faire pour eux (*).

Je suis contre les plug-ins-documentation automatique la plupart des gens recommander car ils créent des commentaires génériques que vous aurez alors à maintenir.

Je veux des commentaires soient significatifs - si je vois un commentaire, il se démarque et je vais faire attention

.

(*) l'exception est lorsque les interfaces dans le code du public sont très stables et certaines personnes bénéficieront d'explications supplémentaires, même alors j'essaie d'éviter documentant.

Licencié sous: CC-BY-SA avec attribution
Non affilié à StackOverflow
scroll top