Y a-t-il une raison logique de générer automatiquement la documentation du code?
La génération automatique de documentation peut être effectuée avec une variété d'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 des méthodes, des classes, etc. et affiche un anglais qui pourrait les expliquer plus verbalement. Dans le meilleur des cas, il fait ce que le lecteur pourrait déjà faire dans sa tête (exemples tirés de ici ):
/// <summary>
/// Initializes a new instance of the <see cref="Person"/> class.
/// </summary>
public Person() ...
Dans le pire des cas, il peut en fait finir par générer une documentation bizarre qui est en fait trompeuse dans sa tentative de comprendre heuristiquement la signification 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 avec GhostDoc est, "il est intrinsèquement préférable d'avoir une sorte de documentation XML formelle", mais lorsque cette documentation est 100% redondante, Pourquoi? N'est-ce pas simplement gaspiller une tonne d'espace au mieux?
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 sans document si vous n'écrivez pas la documentation vous-même?
[...] documentez tout, 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 sans document si vous n'écrivez pas vous-même la documentation?
Non. La documentation générée par GhostDoc est un passe-partout (semblable à la façon dont la création d'une nouvelle classe OO dans une IDE crée la plaque bouillante pour une classe avec un constructeur ou quelque chose comme ça). La partie utile de la documentation est ce qui suivrait après l'ajout du passe-partout.
Alors que vous devez tout documenter sur votre lieu de travail, il semble que vos collègues aient trouvé le moyen parfait de le contourner: faites semblant.
Dans une langue typée statiquement, la documentation de style Javadoc n'est pas pour les auteurs, c'est pour les consommateurs. La génération automatique permet simplement aux auteurs de conserver plus facilement la documentation que d'autres personnes peuvent consommer.
Si vous utilisez un langage typé et que vous n'écrivez pas de bibliothèque pour une consommation tierce, 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 style javadoc est souvent utilisée pour documenter les types, même pour un usage interne uniquement, mais la génération automatique ne connaît pas les types, donc tout ce qu'elle vous évite est d'éviter la copie manuelle du passe-partout.
Quoi qu'il en soit, ne pensez pas à la génération automatique comme produisant un produit fini. Considérez-le comme la production du passe-partout pour vous, donc toutes les modifications que vous apportez manuellement sont importantes.
Y a-t-il une raison logique de générer automatiquement la documentation du code?
Du point de vue de qui?
Si je dirigeais l'entreprise ou le groupe de développement, il n'y a aucune bonne raison. Je suis résolument dans le camp "les commentaires devraient expliquer pourquoi ". Forcer les gens à commenter les classes/fonctions/propriétés est pire qu'inutile, car ils sont obsolètes, ils induisent le lecteur en erreur, ils sont utilisés comme excuse pour ne pas rendre le code lisible, etc. Ces commentaires perdent du temps à les écrire, à lire le code et les bogues causés par eux. Certains diront que les documents de l'API de style JavaDoc sont une raison de faire le commentaire, mais même sous cet argument, une petite partie de votre code devrait faire partie de l'API publique, et JavaDoc ne remplace pas les documents de l'API réels.
En tant que développeur, j'ai travaillé quelques endroits qui nécessitent commentaires dans ces endroits, malgré mon opinion. Comme je n'ai pas le temps ni la patience d'écrire un tas de conneries que personne ne va utiliser, je le préfère GhostDoc. Cela me permet de passer ce temps à faire des choses qui comptent. Bien plus efficace que de changer la politique d'entreprise.
Une autre bonne chose que j'ai trouvée en utilisant GhostDoc est qu'il sert à vérifier que mes noms sont bons. Si GhostDoc ne peut pas générer une documentation décente pour une fonction, c'est une odeur que mes noms de fonction ou de paramètre peuvent être pauvres. Bien que je n'utilise pas l'outil pour juste cela, c'est un joli petit effet secondaire si je suis obligé de perdre mon temps de toute façon.
[~ # ~] modifier [~ # ~] : J'ai mal compris la question d'origine; bien que je pense que générer documentation (c'est-à-dire non-code documents) peut être extrêmement précieux (voir la réponse originale concernant Doxygen ci-dessous), générer automatiquement commentaires (ce que GhostDoc fait en fait) me semble insensé. Je ne comprends pas pourquoi quelqu'un s'attendrait à ce qu'un programme soit capable de lire du code source non commenté et d'écrire des commentaires qui le clarifieront véritablement.
Il est concevable pour moi qu'un utilitaire de génération de commentaires extrêmement "intelligent" pourrait être programmé pour reconnaître certains modèles et générer des commentaires de style "how"; par exemple, il pourrait reconnaître algorithme de calcul de la variance de Knuth et fournir un commentaire expliquant comment cela fonctionne et pourquoi l'algorithme naïf ne serait pas approprié. Peut-être qu'un tel utilitaire pourrait même être programmé pour reconnaître des 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 le montrer, mais " pourquoi" commentaires, expliquant "pourquoi" une chose particulière est en cours. Comme l'a noté David Hammen dans les commentaires ci-dessous, afin de générer des commentaires "pourquoi", un utilitaire devrait "lire l'esprit du programmeur". C'est évidemment impossible.
Sur la base des exemples donnés, cependant, il semble que GhostDoc n'accomplisse même pas la tâche de créer de véritables commentaires de style "comment". C'est donc, à mon avis, pire qu'inutile, car ce qu'il génère fait peut être stupide et trompeur (comme dans le deuxième exemple).
Réponse originale: pourquoi la documentation automatique extraction et formatage est une bonne idée
Mon équipe logicielle utilise Doxygen. La principale raison en est que nous avons besoin de la documentation non-source-code (c'est-à-dire lisible par les non-programmeurs) des fonctionnalités/comportement/etc du code, mais nous pensons qu'il est préférable de l'intégrer dans le code source lui-même que de le conserver en tant que deuxième document . Cela nous aide à garder la documentation en synchronisation avec le code source (bien que cela ne puisse jamais être complètement assuré, encore moins automatisé) et minimise les frais de rédaction de la documentation (puisque la documentation d'un morceau de code peut être incorporée de manière triviale dans le fichier contenant le code lui-même).
Donc, l'objectif de notre utilisation de Doxygen n'est pas d'extraire des informations du code lui-même, mais de garder 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" qui décrit l'ensemble de notre base de code et plusieurs ensembles de "notes de version" qui décrivent le produit logiciel, mais en fait ne contiennent pas de "documentation de code" réelle dans le sens typique.
Quant à savoir pourquoi nous aurions besoin d'une documentation non code source du comportement de notre code, il y a deux raisons:
- Notre produit n'est pas simplement un logiciel; c'est un outil complexe qui intègre de nombreux composants matériels, dont certains lasers et fluidiques sophistiqués. Nous avons besoin d'ingénieurs sans grande expérience logicielle pour bien comprendre exactement comment les composants internes de notre code se comportent, et leur dire "lire le code source" ne va pas accomplir cela.
- Nous devons suivre un certain nombre de réglementations de qualité, certaines mandatées en interne par l'entreprise et d'autres légalement mandatées par le gouvernement fédéral. Bien que le processus qualité soit (ou du moins puisse être) extrêmement précieux et utile, il implique une quantité non négligeable de frais généraux, dont une partie est le devoir de l'équipe du logiciel de fournir ce type de documentation détaillée du logiciel. Encore une fois, l'intégration de cette documentation avec le code lui-même minimise les frais généraux et nous aide à maintenir la documentation à jour.
Notez que le deuxième point est assez similaire au point soulevé par quelques autres réponses à propos des gestionnaires souhaitant avoir l'assurance (/ des droits de vantardise) de savoir qu'il existe une documentation (quelle que soit la qualité) pour chaque morceau de code source; toutefois, cette façon de l’encadrer ne tient pas compte du fait que la documentation mandatée de l’extérieur peut en fait présenter des avantages légitimes.
Certes, la documentation automatisée est particulièrement utile lorsqu'elle peut reproduire des descriptions pertinentes et pertinentes écrites par les auteurs du code. Sinon, c'est juste un formateur automatique glorifié.
Mais le formatage n'est pas inutile. Il est utile de pouvoir trouver les méthodes publiques d'un composant volumineux d'un seul regard, trié et garanti complet. Si vous avez besoin d'un mutateur frobnick et qu'il n'est pas là, vous know il n'est pas là sans patauger dans 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 parce que vous n'avez pas eu à patauger.)
Donc, oui, la génération automatique de documents ajoute une valeur certains. Certainement pas autant que les managers le supposent probablement, et généralement pas autant qu'un éditeur de copie vraiment bon, mais pas rien.
Je ne connais pas les autres environnements mais quand il s'agit de grands projets (souvent open source) PHP projets que d'autres personnes ont écrits, phpXRef est un épargnant de vie absolu (surtout si le document est mis en ligne) et Google peut l'indexer).
Même un projet mal commenté peut au moins m'aider à retrouver où les choses ont été définies et où elles sont utilisées (par exemple lors de la refactorisation).
Lorsqu'elles sont bien commentées, les pages résultantes forment presque une Bible parfaite pour la base de code (pour mes utilisations de toute façon).
De plus, mon préféré IDE générera automatiquement le bloc de commentaire (si je tape/**) qui fait environ 75% du travail de commentaire pour moi. C'est incroyable combien de choses stupides j'ai a été empêché de commettre au cours de ma vie de codeur juste parce que j'ai dû expliquer à d'autres personnes (et à moi à l'avenir) ce que je fais. Lorsque mon commentaire pour le générateur de doc est plus grand que la méthode, cela signifie généralement que je n'ai pas eu assez de café et pourrait vouloir réfléchir un peu plus.
Ces mêmes blocs de commentaires créent également le texte "d'aide" de l'achèvement en ligne afin que je puisse voir exactement ce qui était attendu (par les autres codeurs) lorsque j'écris l'appel de fonction. C'est un énorme gain de productivité pour moi (en particulier dans les rares cas d'Edge où un autre développeur utile a écrit "pour l'amour de Dieu, fais/ne fais pas X"), ce qui peut économiser 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 complexes (et souvent mal nommés) PHP et l'ordre des arguments dans les méthodes moins fréquemment utilisées. Même avec mon propre code, Je ne me souviens pas toujours des arguments que j'ai spécifiés pour quelque chose que je n'ai pas touché depuis longtemps.
Dans un cas, cela signifiait que la source des problèmes récurrents était que, pour une raison qui se reflétait mal sur les développeurs précédents, certaines fonctions et même des constantes étaient définies dans un grand nombre d'endroits (avec un certain degré d'incohérence pour un "plaisir" supplémentaire). . C'était le signe pour s'éloigner du projet.
Dans les projets plus importants qui ont commencé avant mon arrivée, je peux voir quel développeur (en supposant qu'ils ont marqué le fichier de classe avec un nom et un e-mail) a créé la classe et être simplement en mesure de trouver et de 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 projets dans lesquels je travaille) signifie que la documentation peut garder une trace des choses qui nécessitent un peu plus de travail (ou des fonctionnalités reconnues comme manquantes). Encore une fois, mon IDE garde une trace de ceci et cela seul agit comme un bon guide quant à ce qui nécessite mon attention en premier.
Enfin (et très important pour moi), il supprime la surcharge non triviale d'écrire tout cela et d'essayer de le garder à jour lorsque certains (lire plusieurs) codeurs commettent des modifications et ne parlent pas aux responsables de la documentation.
Donc, les raisons incluent:
- Faire gagner plus de temps aux développeurs ultérieurs,
- Garder une trace de l'endroit où les fonctions sont appelées (et définies),
- Repérer le codage idiot,
- Trouver (comme un autre l'a souligné) quand quelque chose manque manifestement,
- Refactorisation simplifiée (jamais très amusant)
- (Dans de nombreux cas) avoir une idée de ce que le développeur essayait de faire (en supposant qu'il ou elle a laissé des notes).
- Si le projet est suffisamment complexe pour avoir plusieurs licences en cours (pas de plaisir), je peux rapidement voir quelles licences s'appliquent à une section donnée. Certes, c'est un bonus supplémentaire.
- Se faire une idée de la personne à qui parler d'un dossier de projet.
- Listes de tâches automatiques
Aussi, ne sous-estimez pas la valeur de garder les patrons aux cheveux pointus heureux au simple toucher d'un bouton.
En bref, les "commentaires de documentation automatique" sont essentiels à mes habitudes de codage. Je suis sûr qu'il y en a beaucoup qui pensent que c'est boiteux, mais je suis tout aussi sûr qu'il y a pas mal 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é).
Sous cette forme, c'est pire qu'inutile, mais uniquement parce qu'il repose uniquement sur la signature publique (qui, dans le cas de Javadoc, est de toute façon visible pour quiconque lit le document API).
Mais il est possible d'écrire des outils de documentation automatisés qui tiennent également compte du corps de la méthode. Comme preuve de concept, j'ai écrit un petit plugin Eclipse boiteux qui ajoute une liste d'autres méthodes appelées de la méthode documentée au Javadoc. (Pas tous les appels bien sûr, vous pouvez définir des filtres, par package par exemple.)
Et je l'ai trouvé très pratique lors du mappage mental d'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 (qui devrait être posée avant d'écrire 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 grand non car tout ce que vous mettez dans le Javadoc fait techniquement partie de l'API.
Mais si le public cible est d'autres développeurs travaillant sur le même produit, l'ajout automatique d'informations sur les détails d'implémentation, tels que les méthodes qui modifient ou lisent un certain champ, est à la fois acceptable et assez utile.
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 de vrais développeurs. 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 les valeurs de retour déjà remplies, puis j'ajoute simplement la "viande" de la documentation.
En tant que développeur C #, j'utilise Stylecop, qui requiert 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 pourraient être déduits du nom de l'objet, par ex. une classe Person possède un champ ID.
Mais SI je veux commenter une méthode non évidente, il est très facile d'étendre la documentation standard et quelques explications sur ce qu'elle fait. À titre d'exemple: j'ai une méthode sur ma classe Person, qui renvoie FirstName + Lastname, mais j'ai ajouté un peu de docu sur ce qui se passe quand l'un des deux est manquant.
En bref: je pense que le docu passe-partout peut être préjudiciable si vous ne changez jamais le texte fourni par le générateur. Dans ce cas, c'est juste du bruit de ligne. Mais si vous les voyez comme un modèle, ils abaissent la barre pour fournir des commentaires bons 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 (qui dans le cas C # est plutôt bavard et ennuyeux à générer à la main) et cela réduit les chances que vous fournissiez vraiment ce commentaire à al ..
Évitez la tautologie
La seule fois où vous devriez avoir besoin d'une documentation pour le code est d'expliquer pourquoi une méthode/fonction fait quelque chose, le nom devrait suffire pour ce que il fait.
Si vous faites quelque chose qui n'est pas idiomatique ou qui viole le principe du moindre étonnement alors la 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 consommateurs de votre code. Javadoc le fait extrêmement bien.
Tout ne doit pas être documenté manuellement
Des choses comme les méthodes getXXX/setXXX devraient être explicites, donc la documentation auto-générée qui vous permet juste de savoir qu'elles existent sera bien reçue.
La documentation du code, du moins du type "automatique", représente le dénominateur le moins courant pour les personnes essayant 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" qui leur dirait ce (peu) dont ils ont besoin.
Les utilisateurs les moins sophistiqués ne l'apprécieraient pas pour la raison opposée; ils ne le comprendraient pas de toute façon.
Les utilisateurs les plus "appréciés" de la documentation automatique du code sont ceux pour qui "un peu de connaissances" est une chose dangereuse. "Ils peuvent ou non comprendre la documentation (bien qu'ils le soient), mais ils se sentiront bien" d'être "Cette audience comprend la plupart des types" de gestion ". Si c'est votre public principal, la documentation automatique du code peut être une bonne chose.
la réponse simple à "pourquoi générer des documents" peut être simplement répondu en montrant MSDN.
Imaginez-vous essayer d'écrire un programme qui utilise n'importe quelle bibliothèque où il n'y a pas de documentation API. Ce serait un cauchemar. MSDN est un excellent exemple du type de document qui peut être généré à partir du code source et des commentaires et constituer une ressource essentielle pour les développeurs.
Si vous écrivez une application (c'est-à-dire pas une bibliothèque destinée à être consommée par d'autres), il y a peut-être lieu de ne pas être dérangé - mais même dans ce cas, la quantité d'une grande application interne ne contient pas un tas de bibliothèques en tous cas? Lorsque vous vous joignez à une telle équipe, avoir un document API navigable va être utile.
Aucun outil n'écrira votre documentation pour vous, mais ils vous donnent le passe-partout que vous auriez à écrire manuellement de toute façon, certains outils (comme doxygen) généreront également des diagrammes et des listes de référence (des fonctions appelées et appelantes par exemple ) qui ne serait pas facilement découvert 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 ignorées de la génération, même dans les outils), mais à aucun moment, quiconque ne devrait dire "il y a le code source, c'est assez de documentation" à tout moment .