Apa cara yang baik untuk mendokumentasikan perangkat lunak ilmiah?

Sering kali, ketika saya mewarisi atau menemukan kode ilmiah yang ditulis oleh orang lain (atau kadang-kadang, bahkan karya saya sendiri), saya perhatikan bahwa dokumentasi jarang atau tidak ada. Jika saya beruntung, saya melihat komentar informatif. Jika saya sangat beruntung, bahkan ada komentar Doxygen dan Doxyfile sehingga saya memiliki antarmuka fungsi dan beberapa HTML terformat untuk berkonsultasi. Jika saya sangat beruntung, ada manual PDF dan contoh-contoh selain Doxygen dan komentar file sumber, dan saya sangat gembira, karena itu membuat hidup saya jauh lebih mudah.

Informasi dan alat apa yang berguna dalam mendokumentasikan kode sumber? Untuk itu, informasi dan alat apa yang berguna untuk mendokumentasikan data dan hasil yang menyertai kode sumber itu, dalam hal perangkat lunak ilmiah?

Saya pikir dokumentasi untuk perangkat lunak ilmiah dapat dibagi menjadi tiga kategori, yang semuanya diperlukan untuk pemahaman penuh. Yang paling mudah dan paling umum adalah dokumentasi metode individual. Ada banyak sistem untuk ini. Anda menyebutkan doxygen , Python memiliki pydoc , dan dalam PETSc kami memiliki paket kami sendiri yang menabur yang menghasilkan sebagai berikut .

Namun, untuk perangkat lunak apa pun yang melampaui utilitas sederhana, Anda memerlukan manual. Ini memberikan pandangan tingkat tinggi tentang tujuan paket, dan bagaimana berbagai fungsionalitasnya berintegrasi untuk mencapai tujuan ini. Ini membantu pengguna baru menyusun kode mereka, seringkali melalui penggunaan contoh. Dalam PETSc, kami hanya menggunakan LaTeX untuk manual, tetapi paket PyClaw menggunakan kerangka Sphinx yang sangat saya kagumi . Satu hal yang telah kami terapkan dalam paket penaburan yang menurut saya sangat berguna adalah tautan antara kode contoh dan dokumentasi fungsi. Misalnya, contoh inimemecahkan persamaan Bratu. Perhatikan bagaimana Anda dapat mengikuti tautan untuk jenis panggilan fungsi atau fungsi apa pun dan sampai ke dokumentasi tingkat rendah, dan bagaimana halaman-halaman itu menghubungkan kembali ke contoh-contoh menggunakannya. Ini adalah bagaimana saya belajar tentang fungsionalitas baru yang dikontribusikan oleh orang lain dalam proyek.

Bagian dokumentasi yang sering diabaikan, saya pikir, adalah dokumentasi pengembang. Sudah lazim untuk menerbitkan dokumen gaya pengkodean, dan instruksi untuk berinteraksi dengan repositori. Namun, sangat jarang menjelaskan keputusan desain yang dibuat sebelum implementasi. Keputusan ini selalu melibatkan pengorbanan, dan situasi sehubungan dengan perangkat keras dan algoritme akan selalu berubah seiring waktu. Tanpa diskusi tentang tradeoffs ditinjau dan alasan untuk keputusan desain tertentu, programmer kemudian dibiarkan menciptakan kembali seluruh proses sendiri. Saya pikir ini adalah hambatan utama untuk keberhasilan pemeliharaan dan peningkatan kode lama ketika pengembang asli tidak lagi bertanggung jawab.

Dokumentasi dalam kode

Yang paling penting adalah menggunakan fasilitas dokumentasi di lingkungan pengembangan yang Anda pilih, sehingga itu berarti pydoc untuk python, javadoc di java atau komentar xml dalam C #. Ini memudahkan untuk menulis dokumentasi pada saat yang sama dengan menulis kode.

Jika Anda mengandalkan untuk kembali dan mendokumentasikan sesuatu nanti, Anda mungkin tidak menyiasati hal itu, tetapi jika Anda melakukannya saat Anda menulis kode, maka apa yang perlu didokumentasikan akan menjadi segar dalam pikiran Anda. C # bahkan memiliki opsi untuk mengeluarkan peringatan kompilasi jika dokumentasi XML tidak lengkap atau tidak konsisten dengan kode aktual.

Tes sebagai dokumentasi

Aspek penting lainnya adalah memiliki integrasi yang baik dan pengujian unit.

Seringkali dokumentasi berkonsentrasi pada apa yang dilakukan kelas dan metode secara terpisah, melompati cara mereka digunakan bersama untuk menyelesaikan masalah Anda. Tes sering menempatkan ini ke dalam konteks dengan menunjukkan bagaimana mereka berinteraksi satu sama lain.

Demikian pula, tes unit sering menunjukkan ketergantungan eksternal secara eksplisit melalui mana hal-hal yang perlu diejek .

Saya juga menemukan bahwa menggunakan pengembangan yang digerakkan oleh Test, saya menulis perangkat lunak yang lebih mudah digunakan, karena saya menggunakannya langsung dari kata go. Dengan kerangka pengujian yang baik, membuat kode lebih mudah untuk diuji dan membuatnya mudah digunakan seringkali merupakan hal yang sama.

Dokumentasi tingkat tinggi

Akhirnya ada apa yang harus dilakukan tentang tingkat sistem dan dokumentasi arsitektur. Banyak yang menganjurkan menulis dokumentasi seperti itu di wiki atau menggunakan Word atau pengolah kata lain, tetapi bagi saya tempat terbaik untuk dokumentasi semacam itu adalah di samping kode, dalam format teks biasa yang ramah sistem kontrol versi.

Sama seperti dengan dokumentasi dalam-kode, jika Anda menyimpan dokumentasi tingkat yang lebih tinggi dalam repositori kode Anda, maka Anda akan cenderung memperbaruinya. Anda juga mendapatkan manfaat bahwa ketika Anda mengeluarkan versi XY kode, Anda juga mendapatkan versi XY dokumentasi. Selain itu, jika Anda menggunakan format ramah VCS, maka itu berarti mudah untuk melakukan percabangan, diff, dan menggabungkan dokumentasi Anda, seperti halnya kode Anda.

Saya sangat suka reStructuredText (pertama) , karena mudah untuk menghasilkan halaman html dan dokumen pdf dari itu menggunakan sphinx , dan jauh lebih ramah daripada LaTeX , namun masih dapat menyertakan ekspresi matematika LaTeX saat Anda membutuhkannya.

Saya akan keberatan dengan hampir setiap poin yang dibuat Faheem . Secara khusus:

1 / "Saya pikir tidak realistis mengharapkan pengembang ilmiah menghabiskan banyak waktu untuk mendokumentasikan perangkat lunak mereka". Ini adalah resep untuk proyek gagal yang tak lama lagi tak seorang pun akan dapat menggunakan yang tidak memiliki akses ke pengembang utama. Untuk alasan yang baik bahwa perpustakaan komputasi ilmiah besar (misalnya PETSc, atau deal.II) memiliki dokumentasi yang luas yang mencapai 1.000 halaman atau lebih. Anda tidak dapat memiliki komunitas pengguna yang cukup besar jika Anda tidak memiliki dokumentasi yang luas. Saya akan setuju, bagaimanapun, bahwa kode contoh harus sederhana dan fokus pada satu konsep.

2 / "penulis harus mempertimbangkan untuk menulis makalah untuk publikasi jika sesuai". Itu sering tidak mungkin dalam praktek. Seseorang dapat menulis makalah tentang konsep dan algoritma, tetapi tidak pada antarmuka dan keputusan desain lainnya. Pembaca makalah semacam itu akan mendapatkan ide apa implementasi melakukannya; pengguna implementasi perlu mengetahui fungsi apa yang harus dipanggil, apa artinya argumen, dll. Sebagai pengguna, sebagian besar waktu dapat hidup tanpa yang pertama dan cukup menganggap perpustakaan sebagai kotak hitam, tetapi orang tidak dapat melakukannya tanpa informasi antarmuka.

Ini pertanyaan yang bagus. Untuk perkiraan pertama, kode harus berusaha untuk mendokumentasikan diri. Jadi, misalnya, jika perangkat lunaknya adalah baris perintah, Anda harus dapat melakukan executable --helpatau executable -hatau bahkan executable(jika yang dapat dieksekusi tidak melakukan apa-apa tanpa argumen), dan mengembalikan pesan penggunaan singkat.

Kedua, saya pikir itu tidak realistis untuk mengharapkan pengembang ilmiah menghabiskan banyak waktu untuk mendokumentasikan perangkat lunak mereka, jadi saya sarankan agar tetap sederhana. Manual teks pendek dengan metode dan opsi dasar dan pekerjaan yang teranotasi dan terujicontoh penggunaan, lulus dari yang sederhana ke yang lebih rumit (contoh penggunaan sangat penting dan sering diabaikan) jauh lebih baik daripada tidak sama sekali dan jauh lebih banyak daripada kebanyakan penawaran perangkat lunak ilmiah. Saya juga ingin menambahkan hewan peliharaan kesal tentang contoh penggunaan. Sederhana berarti sederhana. Itu berarti jika Anda mencoba mengilustrasikan suatu metode, Anda tidak menambahkan sepuluh konsep atau metode asing untuk membingungkan pembaca. Buat sederhana dan membubuhi keterangan sehingga pembaca tahu apa yang seharusnya dilakukan oleh contoh. Saya juga menyarankan untuk mengikat contoh penggunaan manual ke dalam test suite entah bagaimana sehingga mereka terus bekerja ketika kode diubah. Saya sebenarnya tidak tahu bagaimana melakukan ini dengan cara yang baik, jadi silakan mendidik saya. Jika pengembang ingin lebih menyukai, yakin mereka dapat menggunakan bahasa markup yang bagus dan sebagainya, tambahkan halaman manual dan sebagainya.

Ketiga, penulis harus mempertimbangkan untuk menulis makalah untuk publikasi jika sesuai. Ini biasanya akan membahas keputusan desain dan memberikan perspektif tingkat lebih tinggi pada perangkat lunak daripada manual, atau dapat diharapkan untuk dilakukan. Ini akan membahas dokumentasi keputusan desain yang dibicarakan oleh @Matt.

Tentu saja, dokumentasi yang paling penting dari semua adalah kode itu sendiri, yang harus dikomentari seperlunya. Ini mengasumsikan kode tersebut adalah perangkat lunak bebas. Jika tidak, maka itu secara substansial kurang bermanfaat sebagai perangkat lunak ilmiah (apakah Anda benar-benar ingin menggunakan kotak hitam di mana Anda tidak dapat melihat bagaimana metode diimplementasikan?) Dan saya tidak akan menggunakannya.

Untuk menjawab pertanyaan Anda tentang cara mendokumentasikan data dan hasil, saya akan merekomendasikan sesuatu seperti modul doctest Python . Ini memungkinkan Anda untuk menulis tutorial atau tes dengan cara yang dapat divalidasi secara otomatis.

Jika Anda tertarik pada pemrograman melek huruf, silakan lihat org-babel . Ini adalah bagian dari mode-org di Emacs dan dengan demikian memberi Anda beragam pilihan ekspor (LaTeX, PDF, HTML, ODT) untuk dokumentasi. Emacs dapat menampilkan gambar di dalam buffer dan membiarkan Anda menulis persamaan matematika di sintaks LaTeX sehingga Anda tidak perlu membatasi diri pada dokumentasi teks biasa.

Dokumentasi yang secara otomatis diturunkan dari kode sumber Anda adalah komponen penting dalam mendapatkan yang terbaru yaitu dokumentasi yang benar. Saya tidak bisa menghitung berapa kali saya telah melihat dokumentasi yang bertahun - tahun di belakang kode sumber karena apatis pengembang terhadap dokumentasi. Solusi mudahnya adalah untuk memudahkan para programmer untuk menulis dokumentasi bersama dengan kode baru di tempat yang sama pada saat yang sama daripada sebagai upaya posteriori yang pasti akan diprioritaskan untuk mendukung kegiatan yang lebih mulia.

Jika terpaksa memilih, saya lebih suka komentar kode sumber yang terperinci dan akurat (yaitu saat ini) tetapi tidak ada manual pengguna apa pun selain manual pengguna yang ketinggalan zaman yang penuh dengan informasi yang salah.

Dalam Python ada alat pep8 dan pep257 yang akan melaporkan dokumentasi yang hilang atau salah. elpy untuk Emacs juga akan mengeluh tentang dokumentasi yang hilang. The Numpy docstring konvensi dengan reStructuredText baik untuk diikuti. Tes dengan pep8, pep257 dan doctest dapat diatur dengan py.test dan toks berjalan secara otomatis.