Pour comprendre le rôle de JSDoc
Par exemple, ce fichier : https://github.com/showdownjs...
J'y ai pensé moi-même :
Laissez l'interface js, 变得静态 (en fait principalement 3)
Facile à générer des documents
Pratique pour l'IDE, et également pratique pour les développeurs pour appeler des interfaces
Alors, quels sont les avantages pratiques ?
![[Web front-end] Démarrage rapide de Node.js](https://img.php.cn/upload/course/000/000/067/662b5d34ba7c0227.png)
Que vous écriviez du JSDoc ou non, l'interface de JS est très dynamique. La fonction peut également utiliser des méthodes dynamiques telles que
arguments和callpour transmettre différents formats de paramètres, et elle peut même ne pas correspondre à la liste de paramètres du récepteur.En termes de génération de documents, JSDoc peut en effet réaliser une génération rapide de documents. Mais cela a des exigences plus élevées sur le mode d'organisation des modules de code, la longueur des commentaires et le niveau des développeurs, et les documents générés automatiquement ne sont généralement pas aussi lisibles que ceux directement maintenus (par exemple, Yeoman, la plupart des documents générés automatiquement lors du traitement avec des relations d'héritage inexplicables).
En termes d'amélioration de l'expérience de développement, l'écriture de JSDoc peut en effet améliorer l'intelligence de l'EDI dans les invites de code, et peut également coopérer avec eslint pour découvrir des problèmes potentiels pendant la phase de développement/compilation (packaging).
De plus, lors de la refactorisation du code, une question souvent rencontrée est [lors de l'exécution ici, quel type doit être cette variable et quelle valeur doit-elle prendre dans cet état ? 】Étant donné que le front-end et le back-end programment en fait autour des données, si vous utilisez des types de données très dynamiques et manquez de documentation, vous aurez souvent du mal à comprendre lors de la maintenance ou de la refactorisation du code [Qu'est-ce que la fonction entre et renvoie ? What], et JSDoc peuvent améliorer efficacement cela.
Cependant, je suppose que ce que la personne qui pose la question veut vraiment demander est : [Puisque JSDoc présente de nombreux avantages, dois-je utiliser cette fonctionnalité dans mon code métier ? 】
Cette question et [Dois-je écrire des tests unitaires] sont en fait le même type de question. Tout le monde sait que l’écriture de tests unitaires et de JSDoc présente de nombreux avantages, mais le problème est également très évident : ils vont augmenter la quantité de code et la durée du cycle de développement. Contrairement au code de test unitaire dans un répertoire de test distinct, JSDoc augmente directement la longueur du code métier (sauf si vous utilisez de nouvelles méthodes Doc telles que la spécification TypeScript). Par conséquent, dans la pratique, pour les codes métiers qui ne sont pas hautement réutilisables, il n'y a aucun problème sans écrire du JSDoc ou des tests unitaires (le répondant a travaillé dans plusieurs usines pas si petites, et les codes métiers réels de chaque front-end sont basés sur une implémentation fonctionnelle). Pour commencer, ce serait bien si vous n'écrivez pas de code de nouilles. Comment puis-je avoir le temps d'ajouter une documentation longue pour vous, bien sûr, pour les postes back-end qui sont essentiellement ? sur la base de la recherche dans la table et du retour des données, il est plus facile d'écrire les spécifications respectives). Lorsque vous réinventez la roue et publiez des modules de code réutilisables, des tests JSDoc et unitaires complets sont bénéfiques pour la maintenabilité du module et peuvent également donner aux utilisateurs le sentiment que « la qualité du code est vraiment bonne ».
Pour faire simple, démarrez JSDoc dès que possible. Le plus important est de terminer le code métier plus tôt et de ne pas faire d'heures supplémentaires.