Studi tentang dokumentasi kode keuntungan / kerugian produktivitas

Setelah banyak pencarian, saya gagal menjawab pertanyaan dasar yang berkaitan dengan asumsi yang dikenal di dunia pengembangan perangkat lunak:

APA YANG DIKETAHUI:

Menegakkan kebijakan ketat pada dokumentasi kode yang memadai (baik itu tag Doxygen, Javadoc, atau sekadar banyak komentar) menambah terlalu banyak waktu yang diperlukan untuk mengembangkan kode.

TAPI:

Memiliki dokumentasi menyeluruh (atau bahkan API) membawa serta peningkatan produktivitas (satu asumsi) di pengembang baru dan berpengalaman ketika mereka menambahkan fitur, atau memperbaiki bug di jalan.

PERTANYAAN:

Apakah penambahan waktu pengembangan diperlukan untuk menjamin dokumentasi tersebut diimbangi dengan perolehan produktivitas di jalan (dalam arti ekonomis)?

Saya mencari studi kasus, atau jawaban yang dapat membawa bukti objektif yang mendukung kesimpulan yang diambil.

Terima kasih sebelumnya!

Artikel "Gaya tipografi lebih dari sekadar kosmetik" agak lama tetapi sangat menarik: http://portal.acm.org/citation.cfm?id=78611 .

Menjadi tua, itu tidak termasuk semua hal-hal mewah yang mungkin dilakukan hari ini tetapi itu menunjukkan dengan jelas bahwa dokumentasi kode itu penting.

Bagi mereka yang, seperti saya, tidak memiliki akses ke perpustakaan digital ACM, mereka menciptakan dua kelompok programmer dan memberi mereka kode yang sama untuk dipelajari. Grup A hanya menerima kode dengan komentar biasa, grup B menerima daftar yang dicetak dengan daftar isi, referensi silang dan semua hal yang mungkin dilakukan pada tahun 1990.

Kemudian mereka meminta kedua kelompok untuk melakukan tugas-tugas tertentu pada kode (misalnya memperluas fungsi, menemukan bug, ...) dan memberi nilai pada mereka dalam hal kecepatan dan kualitas jawaban.

Untuk menyeimbangkan kelompok, mereka memiliki jumlah ahli dan programmer junior yang sama.

Nah, ternyata kelompok B (yang dengan daftar tercetak cantik) secara alami mendapat nilai lebih baik daripada kelompok A dalam berbagai tes. Dan, pada kasus tertentu, hanya yang paling ahli dari grup A yang berhasil melampaui programmer junior dari grup B.

Artikel itu mengatakan lebih banyak tetapi ini adalah apa yang dapat saya ingat dari memori (saya masih harus memiliki artikel yang dicetak di suatu tempat).

Bagi saya setidaknya, tampak jelas bahwa kode yang dapat dibaca bernilai jauh lebih banyak daripada dokumentasi yang hanya berfungsi untuk menebus kode yang ditulis dengan buruk. Saya cenderung menganggap komentar dalam kode sebagai tantangan untuk melihat apakah saya dapat menghapus komentar dengan menulis ulang kode dan membuatnya lebih menjelaskan diri.

Saya tidak bisa mendukungnya dengan bukti keras, kecuali akal sehat.

Saya tidak memiliki studi untuk dikutip, tetapi saya memiliki aturan sederhana: jika saya kembali ke kode saya dua minggu kemudian dan tidak dapat segera mengetahui apa yang saya lakukan, itu perlu lebih banyak komentar, atau perlu disederhanakan .

Tentu saja, cara kerja kode Anda harus didokumentasikan oleh kode itu sendiri. Tetapi waktu yang dihabiskan untuk menulis komentar yang dengan hati-hati dan singkat menjelaskan mengapa kode Anda ditulis dengan cara yang hampir pasti membayar untuk dirinya sendiri dalam jangka panjang, bahkan jika Anda adalah satu-satunya orang yang memelihara kode tersebut.

Seumur hidup sepotong perangkat lunak akan dihabiskan sebagian besar dalam tahap pemeliharaan, sehingga apa pun yang membantu programmer datang setelah Anda untuk memahami apa yang terjadi hampir pasti akan memberikan pengembalian finansial, karena itu membantu pengembang untuk mempercepat lebih cepat.

Pada API apa pun yang sedikit tidak sepele mendokumentasikan API dalam kode itu hampir tidak berguna. Ini karena kekuatan di API berasal dari cara kerjanya bersama-sama sebagai satu kesatuan (bukan cara kerja masing-masing metode / objek).

Dengan demikian, yang lebih bermanfaat daripada dokumentasi sebenarnya adalah dokumen seperti buku masak yang menjelaskan pola penggunaan API yang diharapkan, dan contoh cara mengatasi beberapa situasi yang jelas (yang menggunakan mayoritas (bukan 100%) dari API).

Keputusan apakah metode yang diberikan adalah, tanpa alat yang mungkin belum ditemukan, terlalu subyektif untuk mengharuskan dokumentasi ditulis.

Praktik tebakan terbaik, seperti "semua metode publik" atau semua kelas dalam paket yang diberikan, dll., Dapat membantu tetapi terlalu kasar untuk direkomendasikan di luar kasus penggunaan khusus.

Saran saya: Ajari pengembang Anda praktik yang baik, cara mengidentifikasi metode yang penting untuk didokumentasikan (API formal atau informal, yang biasa digunakan, metode rintisan, kompleks atau esoterik) dan biarkan mereka mengatur sendiri.

(Terkait erat: Dapatkah ada terlalu banyak keseragaman dalam standar pengkodean? )

^{Maaf bahwa saya tidak memiliki studi untuk mengutip, tapi saya curiga bahwa ini adalah masalah di mana setiap upaya untuk mengukurnya akan mempengaruhi hasil terlalu besar untuk menarik kesimpulan umum.}

Saya pikir kita perlu memisahkan kode "reguler" dari API publik dalam hal ini. Untuk kode reguler saya sangat setuju dengan sebagian besar penjawab lain dalam kode yang harus mendokumentasikan diri sendiri dan membaca hampir seperti prosa . Jika kode saya tidak seperti itu, itu biasanya kesalahan saya, jadi daripada mendokumentasikan, kode itu harus dire-refored. Metode kecil yang hanya melakukan satu hal pada satu waktu, bekerja pada satu tingkat abstraksi, memiliki nama yang benar dan deskriptif , bisa menjadi cara yang bagus untuk mencapai ini.

Masalah dengan komentar adalah mereka membusuk. Segera setelah Anda menambahkan komentar, itu mulai menjalani kehidupan yang terlepas dari kode yang menyertainya. Seberapa besar kemungkinan pengembang berikutnya yang memodifikasi kode akan dengan patuh memperbarui komentar terkait juga? Dalam pengalaman saya, mendekati nol. Hasil akhirnya setelah beberapa modifikasi adalah bahwa komentar tersebut membingungkan atau menyesatkan orang daripada membantu mereka.

Pengecualian yang mungkin adalah kode yang dioptimalkan kinerja, atau menggunakan algoritma tertentu . Dalam hal ini berguna untuk menambahkan komentar untuk menjelaskan mengapa kode itu seperti itu, referensi ke algoritma dll.

Pekerjaan mani pada topik ini adalah Kode Bersih .

OTOH, API publik harus benar-benar didokumentasikan dengan baik di Javadoc juga. Karena dapat digunakan oleh orang asing yang tak terhitung jumlahnya dengan keterampilan dan asumsi yang sangat beragam, kita harus melakukan tindakan pencegahan untuk membuatnya sesederhana dan jelas untuk digunakan sebanyak mungkin. Itu masih sebagian besar masalah desain API yang tepat, tetapi ada peran penting untuk dokumentasi juga.

Masalahnya adalah apakah Anda menghemat waktu dengan mendokumentasikan kode Anda versus setiap pengembang berikutnya harus mencoba mencari tahu apa yang dilakukannya. Jika kode Anda terbang melalui tinjauan kode tanpa ada yang mengajukan pertanyaan tentang apa yang dilakukannya, Anda mungkin dalam kondisi yang baik. Tidak terlalu sulit untuk menggambarkan asumsi yang Anda buat tentang input. Katakanlah metode Anda mengambil objek integer dan mengembalikan objek string. Bisakah int menjadi nol? Apakah ada nilai min / maks (selain integer.MinValue / MaxValue)? Bisakah mengembalikan string kosong atau null? Apakah ada pengecualian? Tentu saja siapa pun dapat menemukannya dengan inspeksi, tetapi jika cukup pengembang lain akan menggunakan kode Anda, menghemat setiap beberapa menit adalah sepadan dengan waktu Anda. Juga, ini memberikan penguji kaki untuk membuat tes untuk mengkonfirmasi kode Anda.

Ini tentu saja merupakan topik yang menarik karena selalu ada argumen apakah pengembang harus menghabiskan waktu membuat atau memelihara dokumen atau tidak tetapi kenyataannya adalah bahwa kode harus ditulis dengan baik dan sangat baik dikomentari, cara ini ketika pengembang mengunjungi kembali kode daripada dia tidak perlu menghabiskan waktu merenungkan bagaimana kode ditulis dan apa yang seharusnya dilakukan di tempat pertama apalagi jika anggota tim baru bergabung dengan tim daripada dia juga dapat memahami fungsi dan kerja kode karena telah didokumentasikan dengan jelas.

Jadi kode harus dikomentari dengan baik dan demikian juga kode yang didokumentasikan sendiri yang tidak memerlukan dokumentasi eksternal.

Dalam karir saya, saya telah melihat kode dengan berbagai tingkat dokumentasi dan kualitas (perhatikan bahwa dokumentasi dan kualitas adalah masalah orthoganal). Saya lebih suka waktu yang dihabiskan untuk dokumentasi digunakan untuk meningkatkan kualitas. Untuk kasus sederhana ada alat seperti GhostDoc yang dapat melihat fungsi dan menghasilkan komentar dokumen untuk Anda. Jika GhostDoc dapat menghasilkan komentar yang bermakna yang mengatakan apa fungsi Anda, maka Anda jelas-jelas telah mencapai tujuan memiliki fungsi-fungsi terkenal.

Dalam banyak kasus, GhostDoc bahkan tidak bisa mulai memberi tahu Anda apa fungsi sebenarnya. Waktu Anda lebih baik dihabiskan untuk mengatasi masalah itu dan (mungkin) menggunakan ghostdoc untuk secara otomatis menghasilkan kode Anda.

Lihat Clean Code dan PPP dari Bob Martin untuk diskusi lebih lanjut.