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?