Dokumentasi kode sumber yang di-hyperlink, dieksternalisasi [ditutup]

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?

Masalah ini mengganggu saya sepanjang waktu, dan saya baru saja mendapat ide tentang arah yang harus kita coba dan selesaikan (itulah cara saya menemukan pertanyaan ini).

Saya pikir masalah dokumentasi tertaut dianggap salah ketika kami memutuskan untuk memasukkan dokumentasi pengguna dalam kode sumber. Seperti halnya docco.

Pertama-tama, mari kita bedakan komentar kode dari dokumentasi pengguna.

Komentar kode biasanya dalam kondisi terbaik ketika mereka pendek, sebenarnya sangat pendek, jadi saya benar-benar dapat membaca kode yang melakukan hal-hal tanpa harus melihat beberapa puisi tentang mengapa dan bagaimana kerjanya.

Komentar pengguna ditujukan untuk orang yang mencoba menggunakan perpustakaan / API Anda, dan dapat menyertakan contoh penggunaan, penjelasan mengapa itu diterapkan seperti itu, atau instruksi tentang cara memperluas perpustakaan. Komentar semacam ini cenderung sangat bertele-tele.

Saya setuju pada kenyataan bahwa dokumentasi harus ditulis dalam teks biasa sehingga tidak diperbaiki vendor dan mudah untuk ditambahkan dalam VCS. Tapi saya pikir menyimpan dokumentasi pengguna di file sumber adalah kesalahan besar karena setidaknya dua alasan:

• Sulit membaca kode
• Dokumentasi tidak cukup fleksibel (misalkan saya perlu dua halaman dokumentasi menggunakan kode contoh yang sama atau memiliki satu halaman dokumentasi yang perlu interleave kode dari dua file sumber yang berbeda).

Jadi mengapa kita ingin memilikinya di file yang sama? Yah, tidak ada yang ingin dokumen mereka tidak sinkron dari kode. Tapi kami tetap melakukannya, dan khususnya sekarang adalah hari-hari dengan kesuksesan besar dari Markdown. Yang menurut saya ada di jalur yang benar, tetapi jika jatuh pendek, waaay pendek.

Saat kami menjalin komentar kode dengan komentar pengguna, kami memiliki ikatan 2 arah. Itu memungkinkan kita untuk dengan mudah melihat komentar mana yang sesuai dengan bagian kode mana. Kita juga dapat melihat apakah beberapa kode tidak berdokumen. Apa yang tidak ditawarkan, adalah cara untuk melihat apakah komentar diperbarui atau tidak, dan itu sering terjadi ketika kode Anda sulit dibaca (karena dokumentasi membuatnya jelek).

Bagaimana jika alih-alih memiliki ikatan 2 arah, kita memiliki satu arah ?. Dokumentasi menunjuk ke kode. Kami dapat memiliki kode penurunan harga dengan perintah khusus seperti:

Some documentation right here that explains the following code:
   @include_file <path/to/some/file>:<line_start>-<line_end>
or
   @include_file <path/to/some/file>
     @starts_with "some regexp or literal text to search"
     @ends_with "another regexp"
or
   @include_file <path/to/some/file>
     @class MyClass
     @method foo
or any combination or way of linking you could imagine

We can even have semantic in the directives:
   @explain_code <path/and/same/of/above>
   @example_code <path/and/same/of/above>
   @performance_notice <path/and/same/of/above>

Which would do basically the same, but it adds the intention of why
do we want to add this code in the first place, which could be 
used different by an IDE. 

Ini memiliki keuntungan menjadi markup dengan beberapa tambahan, dan dengan alat yang tepat, kita bisa menambahkan nilai lebih untuk itu.

Bayangkan ini cara mengikat dengan alat seperti gerutuan (bahkan dengan tugas arloji). Anda dapat mendeteksi kapan file sumber berubah, lihat file dokumentasi apa yang bergantung padanya dan memperingatkan pengguna (atau menandainya di suatu tempat) jika kode yang dikomentari telah berubah.

404 halaman tidak ditemukan

Ketika bekerja dengan kode Anda tidak ingin komentar Anda hilang dan itulah yang akan terjadi ketika Anda memisahkan kode dan komentar ke dalam dokumen yang terpisah.

Selain itu, menjaga versi antara dokumen komentar Anda dan dokumen kode akan menyebabkan lebih banyak rasa sakit daripada keuntungan.

Beberapa saran yang Anda buat sangat saya sukai tetapi dapat dengan mudah diimplementasikan sementara juga memiliki kode dan komentar dalam 1 file.

Kemungkinan kerugian yang saya lihat:

• Anda memerlukan editor khusus yang mengimplementasikan fitur ini

• Kode bukan sekadar teks biasa, mudah dimanipulasi dan dikomit ke VCS-es

• Anda perlu dua kali lebih lebar layar untuk bekerja dengan kode

Adapun argumen Anda:

Lebih banyak kode sumber dan lebih banyak dokumentasi di layar sekaligus

Tetapi dapat merepotkan jika Anda ingin melihat dua file berdampingan.

Kemampuan untuk mengedit dokumentasi secara independen dari kode sumber (terlepas dari bahasa?)

Saya berpendapat bahwa itu sebenarnya merupakan kerugian. Saya pribadi mencoba untuk menjaga dokumentasi sedekat mungkin dengan kode, sehingga tidak menjadi ketinggalan zaman.

Tulis dokumentasi dan kode sumber secara paralel tanpa menggabungkan konflik

Sekali lagi, mungkin suatu kerugian. Jika dokumen Anda sangat terkait dengan kode, bagaimana Anda bisa mengeditnya secara independen?

Dokumentasi hyperlink real-time dengan pemformatan teks superior

Jika ada dalam kode, itu sudah real-time;) Adapun hyperlink, melompat ke definisi sudah diterapkan di sebagian besar IDE.

Terjemahan mesin quasi-real-time ke dalam bahasa alami yang berbeda

Saya tidak mengerti mengapa Anda tidak dapat melakukan itu dengan komentar / dokumen reguler.

Setiap baris kode dapat dengan jelas ditautkan ke tugas, persyaratan bisnis, dll.

Ini saya tidak yakin tentang ... Tidak bisakah dicapai dengan komentar reguler?

Dokumentasi dapat secara otomatis cap waktu ketika setiap baris kode ditulis (metrik)

Bukankah VCS sudah menyediakan informasi seperti ini?

Setelah mengatakan ini, saya cukup suka tata letak itu sendiri - tetapi saya tidak melihat perlunya mengubah format file, tidak sulit untuk membuatnya dari komentar reguler. Ada banyak generator dokumentasi yang melakukan itu, misalnya Docco dan penggantinya, seperti Pycco atau Marginalia .

Pertama, komentar dokumen perlu disertakan dengan kode - memindahkannya ke tempat lain hanya membuat hal-hal yang sangat sulit ditangani untuk mendapatkan nol praktis. Jadi kenapa repot-repot!

Apa yang bisa dilakukan adalah mengambil komentar yang disematkan dan menyembunyikannya di editor, menunjukkannya dalam gelembung atau tooltip atau yang lainnya sesuai kebutuhan. Saya berharap bahwa pendekatan semacam itu dapat mendorong orang untuk menulis lebih banyak dokumentasi untuk kode - misalnya, deskripsi kelas bisa pergi dengan kelas daripada di dokumen desain eksternal.

Saat ini Anda dapat menyematkan hyperlink dalam komentar kode, dan Anda dapat menghasilkan dokumen dari kode menggunakan alat seperti Doxygen atau Sphinx. Saya kira itu hanya akan mengambil beberapa ekstensi kode editor untuk mendukung alat ini dengan lebih baik.

Saya tidak akan menautkan baris kode apa pun ke pelacak bug atau alat persyaratan, itu pekerjaan yang lebih baik untuk SCM Anda. Kemudian Anda dapat melihat pengeditan kode per komit yang ditautkan ke tugas. Saya tidak akan mengintegrasikan dokumentasi yang disimpan dalam kode terhadap pelacak bug - Anda akan kacau jika Anda ingin bermigrasi ke yang baru (hmm, saya dapat melihat fitur ini ditambahkan ke TFS sekarang) atau jika Anda kehilangan riwayat komit Anda (yang terjadi)

Selain apa yang sudah menyatakan @Bogdan, saya akan menambahkan beberapa:

• Saya mengkonfigurasi IDE saya untuk selalu memiliki 2 file sekaligus. Dengan fitur yang Anda sarankan, pada dasarnya saya akan membutuhkan 2 monitor untuk melihat jumlah informasi yang sama, dan 3 untuk melakukan apa yang saya lakukan sekarang dengan 2.
• Saat menelusuri file, Anda tidak segera melihat komentar, dan jika Anda tidak tahu persis apa yang Anda cari, sangat sulit untuk menemukannya.
• Saat mencari melalui file, saya tidak dapat mencari melalui komentar secara langsung (atau dengan mudah).
• Terkadang saya perlu melakukan berbagai tes / menulis potongan kode pendek di server langsung, melalui ssh . Meskipun fungsi yang Anda katakan dapat diintegrasikan dengan VIM atau editor baris perintah lainnya - kemungkinan besar akan ada masalah yang cukup besar

• Sebagian besar IDE mendukung kode runtuh / komentar , dengan hasil akhirnya adalah sebagai berikut:

  Alih-alih yang normal:

  

Jadikan kode lebih mudah dibaca, jika Anda tidak perlu komentar.

Kode sumber dan dokumentasi cara itu harus dilakukan.

http://jasmine.github.io/2.3/introduction.html