La génération automatique de documentation peut être réalisée avec divers outils, GhostDoc étant l’un des plus importants. Cependant, par définition, tout ce qu’il génère est redondant. Il examine les noms de méthodes, de classes, etc. et génère un anglais qui pourrait les expliquer plus verbalement. Dans le meilleur des cas, il fait ce que le lecteur pouvait déjà faire dans sa tête (exemples pris ici ):
/// <summary>
/// Initializes a new instance of the <see cref="Person"/> class.
/// </summary>
public Person() ...
Dans le pire des cas, il peut en fait générer une documentation bizarre qui est trompeuse dans sa tentative de déterminer de manière heuristique le sens des noms:
/// <summary>
/// Riches the text selection changed.
/// </summary>
/// <param name="richTextBox">The rich text box.</param>
private void RichTextSelection_Changed(System.Windows.Controls.RichTextBox richTextBox) ...
Il semble que l'attitude vis-à-vis de GhostDoc soit "qu'il est intrinsèquement préférable d'avoir une sorte de documentation XML formelle", mais quand cette documentation est redondante à 100%, pourquoi? N’at-il pas au mieux une perte d’espace?
Sur mon lieu de travail, nous devons tout documenter, et presque toujours avec les documents générés automatiquement par GhostDoc. Faites-vous cela et y a-t-il des raisons rationnelles de ne pas simplement laisser du code non documenté si vous n'écrivez pas réellement la documentation vous-même?
Réponses:
Non. La documentation générée par GhostDoc est une plate-forme (la procédure utilisée pour créer une nouvelle classe OO dans un IDE crée une plaque avec une classe avec un constructeur ou autre). La partie utile de la documentation est ce qui suivrait après l’ajout du passe-partout.
Tandis que vous devez tout documenter sur votre lieu de travail, il semble que vos collègues ont trouvé le moyen idéal de le contourner: faites semblant.
la source
Dans un langage typé statiquement, la documentation de type Javadoc n’est pas destinée aux auteurs, mais au consommateur. La génération automatique permet simplement aux auteurs de gérer plus facilement la documentation destinée à être consommée par d'autres personnes.
Si vous utilisez un langage à typage statique et que vous n'écrivez pas une bibliothèque pour une utilisation par des tiers, la génération automatique ne vous achète pas beaucoup et, selon mon expérience, est rarement utilisée. Si vous utilisez un langage typé dynamiquement, la documentation de type javadoc est souvent utilisée pour documenter les types, même pour un usage interne, mais la génération automatique ne connaît pas les types.
Quoi qu'il en soit, ne pensez pas à la génération automatique comme à la production d'un produit fini. Pensez-y que vous produisez le passe-partout pour vous, donc toutes les modifications que vous apportez manuellement sont importantes.
la source
De quel point de vue?
Si je dirigeais la société ou le groupe de développeurs, il n'y avait pas de bonne raison. Je suis résolument dans le camp "les commentaires devraient expliquer pourquoi ". Forcer des personnes à commenter des classes / fonctions / propriétés est pire que sans valeur, car elles deviennent obsolètes, elles induisent le lecteur en erreur, elles sont utilisées comme excuse pour ne pas créer de code lisible, etc. Ces commentaires font perdre du temps à la fois à les écrire, à lire le code, et aux bugs causés par ceux-ci. Certains diront que les documents d'API de style JavaDoc sont une raison pour les commentaires, mais même avec cet argument, une petite partie de votre code devrait faire partie de l'API publique, et JavaDoc ne remplace pas les documents d'API réels.
En tant que développeur, j'ai travaillé sur quelques lieux qui nécessitent des commentaires, malgré mon opinion. Puisque je n’ai ni le temps ni la patience d’écrire un tas de conneries que personne ne va utiliser, je l’adopte à la place. Cela me permet de passer ce temps à faire des choses importantes. Bien plus efficace que de changer de politique d'entreprise.
Une autre bonne chose que j'ai trouvée en utilisant GhostDoc est que cela sert à vérifier que mes noms sont bons. Si GhostDoc ne parvient pas à générer une documentation correcte pour une fonction, le fait que mes noms de fonction ou de paramètre puissent être médiocres est une odeur. Bien que je n’utilise pas cet outil uniquement pour cela, c’est un joli petit effet secondaire si on me fait perdre mon temps de toute façon.
la source
RichTextSelection_Changedméthode pourrait être plus facile à utiliser si elle appartenait à un objet de sélection et si elle n'était pas nommée d'après le type de son paramètre. Comme l'a dit Telastyn, il ne s'agit que d'une odeur, qui pourrait être bonne ou mauvaise pour votre conception, et mes suggestions n'amélioreront probablement pas la sortie de GhostDoc.EDIT : J'ai mal compris la question initiale; même si je pense que la génération des documents (non code- documents ) peut être extrêmement précieux (voir la réponse originale au sujet Doxygen ci - dessous), création automatique des commentaires ( ce qui est quelque chose qui ne fait GhostDoc) semble fou pour moi. Je ne comprends pas pourquoi quiconque s'attendrait à ce qu'un programme puisse lire du code source non commenté et écrire des commentaires qui le clarifieront réellement.
Il est concevable pour moi qu'un utilitaire extrêmement "intelligent" de génération de commentaires puisse être programmé pour reconnaître certains modèles et générer des commentaires de type "comment"; Par exemple, il pourrait reconnaître l'algorithme de calcul de la variance de Knuth et fournir un commentaire expliquant comment il fonctionne et pourquoi cet algorithme naïf ne serait pas approprié. Peut-être qu'un tel utilitaire pourrait même être programmé pour reconnaître les modèles de conception canoniques orientés objet (par exemple, Abstract Factory) et insérer des commentaires indiquant quel modèle est utilisé et quelles classes jouent quels rôles.
Mais à mon avis, les commentaires les plus utiles n'expliquent pas "comment" quelque chose fonctionne, puisque le code lui-même devrait l'indiquer, mais " pourquoi " commente, expliquant "pourquoi" une chose particulière est en train de se faire. Comme l'a noté David Hammen dans les commentaires ci-dessous, pour générer le "pourquoi" des commentaires, un utilitaire devrait "lire dans l'esprit du programmeur". Évidemment c'est impossible.
Cependant, à partir des exemples donnés, il semble que GhostDoc n'effectue même pas la tâche de créer de véritables commentaires de style "Comment". Il est donc, à mon avis, pire qu'inutile, puisque ce qu'elle ne génère peut être inepte et induire en erreur (comme dans le second exemple).
Réponse originale: pourquoi l' extraction automatique de la documentation et le formatage sont une bonne idée
Mon équipe de logiciels utilise Doxygen. La principale raison à cela est que nous avons besoin d'une documentation non-code source (c'est -à- dire lisible par des non-programmeurs) sur les caractéristiques / comportement du code / etc., mais nous pensons qu'il est préférable d'intégrer cela dans le code source conservez-le comme deuxième document . Cela nous aide à maintenir la synchronisation de la documentation avec le code source (bien que cela ne puisse bien sûr jamais être complètement assuré, encore moins automatisé) et minimise les coûts liés à la rédaction de la documentation (car la documentation d'un morceau de code peut être incorporée de manière triviale à la fichier contenant le code lui-même).
Notre utilisation de Doxygen ne vise donc pas à extraire des informations du code lui-même, mais à conserver la documentation du code source aussi proche que possible du code source lui-même.
Cela nous permet également d’utiliser un seul outil pour créer à la fois une "théorie des opérations" décrivant l’ensemble de notre base de code et plusieurs ensembles de "notes de mise à jour" décrivant le produit logiciel mais ne contenant en réalité aucune "documentation de code". sens typique.
En ce qui concerne les raisons pour lesquelles nous aurions besoin d’une documentation non-code-source du comportement de notre code, il existe deux raisons:
Notez que la deuxième puce est assez similaire à celle que quelques autres réponses ont apportée à propos du fait que les gestionnaires veulent avoir l’assurance (le droit de se vanter) de savoir qu’une documentation (quelle que soit la qualité) existe pour chaque morceau de code source; cette façon de le faire, cependant, ignore le fait que la documentation mandatée de l'extérieur peut présenter des avantages légitimes.
la source
Certes, la documentation automatisée est particulièrement utile lorsqu'elle permet de reproduire des descriptions pertinentes et appropriées écrites par les auteurs du code. Sinon, il ne s'agit que d'un formateur automatique glorifié.
Mais le formatage n'est pas inutile. Il est utile de pouvoir trouver les méthodes publiques d'un composant de grande taille en un seul regard, triées et garanties d'être complètes. Si vous avez besoin d'un
frobnickmutateur, et que celui-ci n'existe pas, vous savez que ce n'est pas possible sans passer par le code source. (Les résultats négatifs ont également de la valeur: vous savez que vous devez faire quelque chose et vous avez plus de temps pour le faire car vous n'avez pas à patauger.)Donc, oui, la génération automatique de documents ajoute une valeur. Certainement pas autant que les gestionnaires le supposent probablement, et généralement même pas autant que le ferait un très bon éditeur de texte, mais pas rien.
la source
frobnickmutateurs ne seront pas nécessairement des développeurs de logiciels; ils peuvent ne pas comprendre comment chercher dans le code source (ce qui peut nécessiter une connaissance degrep/cscope/ack/ etc), et même s'ils trouvent le fichier correct, ils risquent de ne pas trouver le code source réel facile à lire, même s'il est bien commenté d'un point de vue SW. La possibilité de parcourir un index ou un type dans une barre de recherche, puis de parcourir un texte qui ressemble à une page Web peut être très utile.Sous cette forme, c’est pire qu’inutile, mais seulement parce qu’elle repose uniquement sur la signature publique (qui, dans le cas de Javadoc, est visible de toute façon par quiconque lit le document API).
Mais il est possible d'écrire des outils de documentation automatisés qui prennent également en compte le corps de la méthode. Pour prouver le concept, j’ai écrit un petit plugin Eclipse boiteux qui ajoute à la Javadoc une liste d’autres méthodes appelées à partir de la méthode documentée. (Tous les appels ne peuvent bien sûr pas être définis, par exemple, par package.)
Et j’ai trouvé cela très pratique lorsque j’ai dessiné mentalement une base de code complètement inconnue. Certes, c'est un cas d'utilisation très limité, mais c'était certainement une aide.
Sur la base de cette expérience, la réponse à la question est: oui, mais nous avons besoin d'outils beaucoup plus intelligents.
Mise à jour: Bien sûr, une question supplémentaire (à poser avant de rédiger tout type de documentation) est de savoir qui est le public cible. Si nous documentons une API publique pour les clients de cette API, l'ajout de tous ces détails d'implémentation est un non-non, car tout ce que vous insérez dans la Javadoc fait techniquement partie de l'API.
Toutefois, si le public cible est constitué d'autres développeurs travaillant sur le même produit, l'ajout automatique d'informations sur les détails de la mise en œuvre, telles que les méthodes permettant de modifier ou de lire un certain champ est à la fois acceptable et plutôt utile.
la source
Je ne connais pas les autres environnements, mais lorsqu'il s'agit de grands projets PHP (souvent open source) écrits par d'autres personnes, phpXRef est un épargnant de vie absolu (surtout si le document est mis en ligne et que Google peut l'indexer).
Même un projet mal commenté peut au moins m'aider à localiser les éléments définis et leur utilisation (par exemple lors de la refactorisation).
Lorsqu'elles sont bien commentées, les pages résultantes forment presque une Bible parfaite pour le code base (pour mes utilisations de toute façon).
De plus, mon IDE préféré générera automatiquement le bloc de commentaires (si je tape / **), qui effectue environ 75% du travail de commentaire pour moi. Il est étonnant de constater combien de choses stupides qui m'ont empêché de commettre au cours de ma vie de codeur simplement parce que j'ai dû expliquer à d'autres personnes (et à moi futur) ce que je faisais. Lorsque mon commentaire pour le générateur de doc est plus important que la méthode, cela signifie généralement que je n'ai pas assez de café et que je souhaite peut-être réfléchir un peu plus fort.
Ces mêmes blocs de commentaires créent également le texte "aide" de l'achèvement en ligne afin que je puisse voir exactement ce qui était attendu (par les autres codeurs) au moment où j'écris l'appel de fonction. Cela représente un gain de productivité considérable pour moi (en particulier dans les cas rares où un autre développeur utile a écrit "pour l'amour du bien, do / do-not X" - ce qui peut éviter beaucoup de douleur.
Je ne saurais trop insister sur l’utilité d’avoir les types d’entrée attendus spécifiés dans des projets PHP complexes (et souvent mal nommés) et l’ordre des arguments dans des méthodes moins fréquemment utilisées. Même avec mon propre code, je ne peux pas toujours me souvenir des arguments que j'ai spécifiés pour quelque chose que je n'ai pas touché dans une époque.
Dans un cas, cela signifiait que la source des problèmes récurrents était que, pour une raison qui reflétait mal les développeurs précédents, certaines fonctions et même des constantes étaient définies dans un très grand nombre d'endroits (avec un certain degré d'incohérence pour plus de "plaisir") . C'était le signe de s'éloigner du projet.
Dans les projets plus importants qui ont commencé avant que je rejoigne, je peux voir quel développeur (en supposant qu'ils aient balisé le fichier de classe avec un nom et un email) a créé la classe et pouvoir simplement trouver et parler au bon développeur est extrêmement utile.
Listes de tâches automatiques - l'utilisation de la balise @todo (courante dans le type de projet dans lequel je me trouve) signifie que la documentation peut garder trace de choses qui nécessitent un travail supplémentaire (ou de fonctionnalités manquantes). Encore une fois, mon IDE garde la trace de ceci et cela seul est un bon guide pour ce qui nécessite mon attention en premier.
Enfin (et très important pour moi), cela supprime la surcharge non triviale d'écrire tout cela, puis d'essayer de le garder à jour lorsque certains (lisent beaucoup) des développeurs engagent des modifications et ne parlent pas aux responsables de la documentation.
Donc, les raisons incluent:
Ne sous-estimez pas non plus l’importance de garder heureux les patrons aux cheveux pointus par simple pression sur un bouton.
En bref, les "commentaires de documentation automatique" sont essentiels à mes habitudes de codage. Je suis sûr que beaucoup pensent que c'est boiteux, mais je suis tout aussi convaincu qu'il y a assez peu de gens qui savent exactement ce que je dis. Je ne sais pas comment j'ai survécu avant de découvrir phpXRef (et mon IDE préféré).
la source
Il est souvent bon d'utiliser des générateurs de documentation pour créer des commentaires standard ou "stand-in" qui sont ensuite révisés par les développeurs eux-mêmes. J'utilise souvent la fonction auto-JavaDoc d'Eclipse pour générer le commentaire d'en-tête avec les types de paramètres et renvoyer les valeurs déjà renseignées, puis ajoute simplement le "contenu" de la documentation.
la source
En tant que développeur C #, j'utilise Stylecop, qui commande des commentaires pour toutes les classes, méthodes, etc. Je génère automatiquement ces commentaires à l'aide d'un outil. La plupart du temps, les commentaires générés par l'outil sont suffisants et peuvent être déduits du nom de l'objet, par exemple une classe Personne et un champ ID.
Mais si je veux commenter une méthode non évidente plus loin, il est très facile d’étendre la documentation standard et quelques explications sur ce qu’elle fait. A titre d'exemple: j'ai une méthode sur ma classe Person, qui renvoie FirstName + Lastname, mais j'ai ajouté un peu de documentation sur ce qui se passe quand l'une des deux est manquante.
En bref: je pense que le programme standard peut être préjudiciable si vous ne modifiez jamais le texte fourni par le générateur. Dans ce cas, c'est juste du bruit de ligne. Mais si vous les considérez comme un modèle, ils abaissent le niveau de capacité pour fournir des commentaires positifs et utiles à vous-même ou à vos consommateurs. Pourriez-vous écrire les commentaires sans les générer automatiquement? Bien sûr, mais vous devrez respecter le format (ce qui dans C # est plutôt verbeux et gênant à générer à la main) et cela réduit les chances que vous fournissiez réellement ce commentaire à al ..
la source
Éviter la tautologie
Le seul moment où vous devriez avoir besoin de n'importe quel type de documentation pour le code est d'expliquer pourquoi une méthode / fonction est en train de faire quelque chose, le nom devrait suffire à ce qu'elle fait.
Si vous faites quelque chose qui n'est pas idiomatique ou qui enfreint le principe du moindre étonnement, une documentation est requise.
La documentation générée automatiquement qui n'est qu'un formateur pour la sortie d'informations est presque demandée par les utilisateurs de votre code. Javadoc le fait extrêmement bien.
Tout ne doit pas être documenté manuellement
Des méthodes telles que getXXX / setXXX doivent être explicites, donc la documentation générée automatiquement qui vous laisse savoir qu’elles existent sera bien reçue.
la source
La documentation de code, du moins du type "automatique", représente le plus petit dénominateur commun pour les personnes qui tentent de comprendre l'application.
Les utilisateurs les plus sophistiqués n'apprécieraient pas la documentation automatique du code. Ils préféreraient de loin avoir une documentation "ciblée" leur indiquant le peu de choses dont ils ont besoin.
Les utilisateurs les moins sophistiqués ne l'apprécieraient pas pour la raison opposée; ils ne comprendraient pas de toute façon.
Les utilisateurs les plus "reconnaissants" de la documentation de code automatique sont ceux pour qui "un peu de connaissance" est une chose dangereuse. "Ils peuvent ou non comprendre la documentation (bien qu'ils le soient susceptibles), mais ils se sentiront bien d'être" Cette audience comprend la plupart des types "managériaux". Si tel est votre public principal, la documentation automatique du code peut être une bonne chose.
la source
la réponse simple à "pourquoi générer des documents" peut être résolue simplement en montrant MSDN.
Imaginez que vous essayez d’écrire un programme qui utilise n’importe quelle bibliothèque sans documentation API. Ce serait un cauchemar. MSDN est un excellent exemple du type de doc qui peut être généré à partir de code source et de commentaires et constitue une ressource essentielle pour les développeurs.
Si vous écrivez une application (c’est-à-dire qu’une bibliothèque ne doit pas être utilisée par d’autres), il n’ya peut-être pas lieu de s’inquiéter, mais même dans quelle mesure une application volumineuse, interne uniquement, ne contient pas un grand nombre de bibliothèques en tous cas? Lorsque vous vous joindrez à une telle équipe, il vous sera utile de disposer d’une documentation sur l’API navigable.
Aucun outil ne va écrire votre documentation pour vous, mais ils vous donnent le passe-partout que vous auriez à écrire manuellement de toute façon, certains outils (comme doxygen) vont aussi générer des diagrammes et des listes de références (des fonctions appelées et appelantes par exemple). ) qui ne serait pas facile à découvrir même en regardant le code source.
Évidemment, le bon sens pragmatique doit être appliqué à ce qui est documenté, les propriétés et les fonctions mineures peuvent être ignorées (et exclues de la génération même dans les outils), mais personne ne devrait jamais dire "il y a le code source, c'est assez de documentation" .
la source