Apakah ada studi empiris tentang pengaruh komentar kode sumber pada kualitas perangkat lunak, rawatan dan produktivitas pengembang? [Tutup]

11

Saya seorang penganjur mengomentari kode sumber dan mendokumentasikan produk perangkat lunak. Ini adalah pengalaman pribadi dan pengamatan saya bahwa bekerja pada kode sumber yang dikomentari dengan ketat telah membantu saya dalam berbagai cara ketika saya harus mengembangkan perangkat lunak atau memeliharanya.

Namun ada kamp lain yang mengatakan komentar pada akhirnya tidak berharga atau nilainya dipertanyakan. Banyak pendukung pengkodean tanpa komentar berpendapat bahwa:

  • Jika sepotong kode ditulis dengan baik, itu jelas dan karenanya tidak perlu berkomentar
  • Jika sepotong kode tidak jelas, maka refactor dan buatlah itu sendiri sehingga tidak perlu komentar
  • Test suite Anda adalah dokumentasi langsung Anda
  • Dari waktu ke waktu kode dan komentar keluar dari sinkronisasi dan itu menjadi sumber sakit kepala lainnya
  • Agile mengatakan kode kerja lebih penting daripada tumpukan dokumentasi, jadi kita dapat dengan aman mengabaikan menulis komentar

Bagi saya ini hanya dogma. Sekali lagi, pengamatan pribadi saya adalah bahwa perangkat lunak yang ditulis oleh tim pengembang yang cerdas dan berpengalaman akhirnya berakhir dengan sejumlah besar kode yang tidak jelas.

Sekali lagi, Java API, Cocoa API, Android API, dll. Menunjukkan bahwa jika Anda ingin menulis dan memelihara dokumentasi yang berkualitas, itu mungkin.

Setelah mengatakan semua ini, percakapan tentang pro dan kontra dokumentasi dan mengomentari kode sumber yang didasarkan pada kepercayaan pribadi biasanya tidak berakhir dengan baik dan tidak menghasilkan kesimpulan yang memuaskan.

Karena itu saya mencari makalah akademis dan studi empiris tentang efek dokumentasi perangkat lunak, terutama mengomentari kode sumber, pada kualitas dan pemeliharaannya serta pengaruhnya terhadap produktivitas tim.

Sudahkah Anda menemukan artikel seperti itu dan apa hasilnya, jika ada?

productivity documentation code-quality maintainability engineering Behrang Saeedzadeh
sumber
2
Saya pikir ini adalah pertanyaan yang menarik, tetapi saya tidak terlalu terkejut bahwa itu mungkin akan ditutup di sini. Itu sebabnya saya memposting ini di Quora juga.
Behrang Saeedzadeh
4
@gnat - Sepertinya bagi saya bahwa "Penelitian apa yang telah dilakukan dalam aspek pengembangan perangkat lunak ini?" adalah pertanyaan yang agak berbeda dari permintaan "tolong beri saya buku tentang subjek" yang tidak disambut dengan baik.
Josh Kelley
1
Hanya dari membaca judul: Tidak ada studi empiris tentang efek apa pun pada kualitas. Jika ada, situs ini tidak akan ada.
Euforia
2
@Ehhoric dua pernyataan Anda saling bertentangan. Jika kita mengabaikan dokumen "gila" berusia 30 tahun, tidak ada konflik. Tapi bagaimanapun, kita tidak boleh mengabaikan temuan hanya karena mereka sudah tua, tetapi menilai secara kritis bagaimana mereka berhubungan dengan pekerjaan modern (sebagaimana kita seharusnya dengan hasil baru juga).
3
@ Euforia Saya berharap Anda akan memposting itu sebagai jawaban, jadi saya bisa menurunkan jumlah total penelitian Anda dalam pernyataan selimut Anda. Ada banyak makalah dan penelitian, empiris dan sebaliknya, tentang efek teknik yang berbeda pada kualitas perangkat lunak. Sudahkah Anda mempelajari sesuatu tentang Rekayasa Perangkat Lunak?
Andres F.

Jawaban:

9

Dalam "Pengaruh modularisasi dan komentar pada pemahaman program" (1981), Woodfield, Dunsmore, dan Shen menemukan bahwa "subjek yang programnya berisi komentar mampu menjawab lebih banyak pertanyaan daripada yang tanpa komentar."

Namun, dalam "Belajar Metrik untuk Keterbacaan Kode" (2010), Raymond PL Buse dan Westley Weimer menemukan bahwa komentar hanya memiliki efek terbatas pada keterbacaan dan kualitas:

Dari abstrak:

Kami membuat ukuran keterbacaan otomatis dan ... menunjukkan bahwa metrik ini berkorelasi kuat dengan tiga ukuran kualitas perangkat lunak: perubahan kode, laporan cacat otomatis, dan pesan log cacat ... Data kami menunjukkan bahwa komentar, dalam dirinya sendiri, kurang penting dari baris kosong sederhana untuk penilaian lokal keterbacaan.

Dari halaman 12:

Kami menemukan bahwa komentar hanya berkorelasi sedang dengan gagasan keterbacaan annotator kami (daya relatif 33%). Satu kesimpulan mungkin bahwa sementara komentar dapat meningkatkan keterbacaan, mereka biasanya digunakan dalam segmen kode yang mulai kurang dibaca: komentar dan kode yang tidak dapat dibaca secara efektif menyeimbangkan. Efek bersih akan tampak bahwa komentar tidak selalu, dalam dan dari dirinya sendiri, menunjukkan keterbacaan tinggi atau rendah.

Perlu diingat bahwa pendukung "coding tanpa komentar" tidak mengatakan bahwa kode tanpa komentar lebih baik daripada kode dengan komentar. Mereka berargumen bahwa gaya kode tertentu tanpa komentar - yang mengekstraksi kode ke dalam metode dengan nama yang menggambarkan diri sendiri, yang memperkenalkan variabel yang menjelaskan , yang memiliki rangkaian uji yang baik - lebih baik daripada kode yang tidak melakukan hal-hal itu tetapi memiliki komentar. Ini bisa mempersulit penerapan studi apa pun yang telah dilakukan.

Josh Kelley
sumber
1
Makalah Woodfield et al adalah tentang variasi komentar tertentu, kira-kira setara dengan apa yang sekarang disebut Javadoc: "Secara khusus, penelitian ini mencoba untuk menentukan apakah komentar pendek, dimasukkan tepat sebelum modul logis, dapat membantu pemahaman dengan menjelaskan fungsi secara singkat modul logis dan membantu menentukan batas-batas modul logis. "
Saya harus menambahkan pada saat itu: itu tidak berarti tidak memiliki nilai, memang itu studi yang menarik dan dibangun dengan baik. Saya hanya berpikir perlu mengatakan bahwa mereka tidak mengambil semua komentar.