javascript - Apakah kegunaan praktikal dan khusus JsDoc?

Question

Fenomena sebenar

1. Untuk memahami peranan JSDoc

Sebagai contoh, fail ini: https://github.com/showdownjs...

Fenomena yang dijangkakan

Saya memikirkannya sendiri:

1. Biar antara muka js, 变得静态 (sebenarnya 3)

2. Mudah menjana dokumen

3. Mudah untuk IDE, dan juga mudah untuk pembangun memanggil antara muka

Jadi apa faedah praktikalnya?

Answer 1

Sama ada anda menulis JSDoc atau tidak, antara muka JS adalah sangat dinamik. Fungsi ini juga boleh menggunakan kaedah dinamik seperti arguments 和 call untuk lulus dalam pelbagai format parameter, malah ia mungkin tidak sepadan dengan senarai parameter penerima.

Dari segi penjanaan dokumen, JSDoc sememangnya boleh mencapai penjanaan dokumen yang pantas. Walau bagaimanapun, ini mempunyai keperluan yang lebih tinggi pada mod organisasi modul kod, panjang ulasan dan tahap pembangun, dan dokumen yang dijana secara automatik biasanya tidak boleh dibaca seperti yang diselenggara secara langsung (contohnya, Yeoman, kebanyakan dokumen yang dijana secara automatik Apabila berurusan dengan hubungan pewarisan yang tidak dapat dijelaskan).

Dari segi meningkatkan pengalaman pembangunan, penulisan JSDoc sememangnya boleh meningkatkan kecerdasan IDE dalam gesaan kod, dan juga boleh bekerjasama dengan eslint untuk menemui masalah yang berpotensi semasa fasa pembangunan/penyusunan (pembungkusan).

Selain itu, apabila memfaktorkan semula kod, soalan yang sering dihadapi ialah [apabila dijalankan di sini, apakah jenis pembolehubah ini, dan apakah nilai yang perlu diambil dalam keadaan ini? 】Memandangkan kedua-dua bahagian hadapan dan hujung belakang sebenarnya memprogramkan sekitar data, jika anda menggunakan jenis data yang sangat dinamik dan kekurangan dokumentasi, anda sering akan mendapati sukar untuk memahami apabila mengekalkan atau memfaktorkan semula kod [Apakah fungsi input dan pulangan? What], dan JSDoc boleh memperbaiki perkara ini dengan berkesan.

Namun, saya rasa apa yang sebenarnya ingin ditanyakan oleh penyoal ialah: [Memandangkan JSDoc mempunyai begitu banyak faedah, patutkah saya menggunakan ciri ini dalam kod perniagaan saya? 】

Soalan ini dan [Perlukah saya menulis ujian unit] sebenarnya adalah jenis soalan yang sama. Semua orang tahu bahawa menulis ujian unit dan JSDoc mempunyai banyak faedah, tetapi masalahnya juga sangat jelas: mereka akan meningkatkan jumlah kod dan panjang kitaran pembangunan. Tidak seperti kod ujian unit dalam direktori ujian yang berasingan, JSDoc terus meningkatkan panjang kod perniagaan (melainkan anda menggunakan kaedah Doc baharu seperti spesifikasi TypeScript). Oleh itu, dalam praktiknya, untuk kod perniagaan yang tidak boleh diguna semula sangat, tiada masalah sama sekali tanpa menulis JSDoc atau ujian unit (responden telah bekerja di beberapa kilang yang agak kecil, dan kod perniagaan sebenar setiap front-end adalah untuk melaksanakan Untuk tempat pertama, alangkah baiknya jika anda tidak menulis kod mi Bagaimana saya boleh menambah dokumentasi panjang untuk anda pengembalian data, lebih mudah untuk menulis spesifikasi masing-masing). Apabila anda mencipta semula roda dan mengeluarkan beberapa modul kod boleh guna semula, JSDoc dan ujian unit yang lengkap memberi manfaat kepada kebolehselenggaraan modul, dan juga boleh membuatkan pengguna merasakan bahawa "kualiti kod benar-benar baik".

Secara ringkasnya, mulakan JSDoc secepat mungkin. Perkara yang paling penting ialah menyelesaikan kod perniagaan lebih awal dan tidak bekerja lebih masa.