Mengapa kita masih menanamkan deskripsi bahasa alami kode sumber (yaitu, alasan mengapa baris kode ditulis) dalam kode sumber, bukan sebagai dokumen terpisah?
Mengingat real-estate luas yang diberikan pada lingkungan pengembangan modern (monitor resolusi tinggi, monitor ganda, dll.), Sebuah IDE dapat menyediakan panel semi-lock-step di mana kode sumber dipisahkan secara visual - tetapi secara intrinsik terkait dengan - komentar yang sesuai. Misalnya, pengembang dapat menulis komentar kode sumber dalam bahasa marka yang terhubung-hyper (menautkan ke persyaratan perangkat lunak tambahan), yang secara bersamaan akan mencegah dokumentasi dari mengacaukan kode sumber.
Apa kekurangan yang akan menghambat mekanisme pengembangan perangkat lunak seperti itu?
Mock-up untuk membantu memperjelas pertanyaan:
Ketika kursor berada pada baris tertentu dalam kode sumber (ditunjukkan dengan latar belakang biru, di atas), dokumentasi yang sesuai dengan baris di kursor disorot (yaitu, dibedakan dari detail lainnya). Seperti disebutkan dalam pertanyaan, dokumentasi akan tetap terkunci dengan kode sumber saat kursor melewati kode sumber. Tombol pintas dapat beralih antara "mode dokumentasi" dan "mode pengembangan".
Keuntungan potensial meliputi:
- Lebih banyak kode sumber dan lebih banyak dokumentasi di layar sekaligus
- Kemampuan untuk mengedit dokumentasi secara independen dari kode sumber (terlepas dari bahasa?)
- Tulis dokumentasi dan kode sumber secara paralel tanpa menggabungkan konflik
- Dokumentasi hyperlink real-time dengan pemformatan teks superior
- Terjemahan mesin quasi-real-time ke dalam bahasa alami yang berbeda
- Setiap baris kode dapat dengan jelas ditautkan ke tugas, persyaratan bisnis, dll.
- Dokumentasi dapat secara otomatis cap waktu ketika setiap baris kode ditulis (metrik)
- Dimasukkannya secara dinamis diagram arsitektur, gambar untuk menjelaskan hubungan, dll.
- Dokumentasi sumber tunggal (mis., Cuplikan kode tag untuk penyertaan manual pengguna).
catatan:
- Jendela dokumentasi dapat diciutkan
- Alur kerja untuk melihat atau membandingkan file sumber tidak akan terpengaruh
- Bagaimana implementasi terjadi adalah detail; dokumentasi bisa:
- disimpan di akhir file sumber;
- dipecah menjadi dua file berdasarkan konvensi (
filename.c
,filename.c.doc
); atau - sepenuhnya digerakkan oleh basis data
- Dengan dokumentasi hyperlink, maksud saya menautkan ke sumber eksternal (seperti StackOverflow atau Wikipedia) dan dokumen internal (yaitu, wiki pada subdomain yang dapat referensi silang dokumentasi persyaratan bisnis) dan file sumber lainnya (mirip dengan JavaDocs).
Thread terkait: Ada apa dengan keengganan dokumentasi di industri?
Gson()
objek sedang dipakai dalam kaitannya dengan kelas MainActivity, atau bagaimana kaitannya dengan memecahkan kebutuhan bisnis tertentu. Menjelaskan kode itu sendiri, bukan API yang digunakannya, bisa di jendela terpisah, secara independen dari JavaDocs pihak ketiga.