Saya melihat banyak nomor terbitan dari komentar kode jQuery . (Sebenarnya, ada 69 nomor masalah dalam kode jQuery.) Saya pikir ini akan menjadi praktik yang baik, tetapi saya belum pernah melihat pedoman apa pun.
Jika ini merupakan praktik yang baik, apa pedoman untuk praktik ini?
Jawaban:
Secara umum, saya tidak akan menganggapnya sebagai latihan yang baik. Tetapi dalam kasus luar biasa, ini bisa sangat berguna, yaitu ketika kode harus melakukan sesuatu yang tidak intuitif untuk memperbaiki masalah yang kompleks, dan tanpa penjelasan apa pun akan ada risiko bahwa seseorang mungkin ingin "memperbaiki" kode aneh ini dan dengan demikian memecahkannya , sambil menjelaskan alasannya akan menghasilkan komentar besar yang menggandakan informasi dari masalah tersebut.
Saya pikir itu cukup untuk menambahkan nomor masalah ke pesan komit ketika Anda melakukan perbaikan terkait ke sistem kontrol sumber Anda.
Sebagai contoh:
Bug # 203: Koneksi basis data tidak lagi habis setelah 30 detik.
Saya menemukan bahwa menambahkan nomor masalah, nama pengembang atau tanggal bahwa perubahan telah dibuat dalam kode hanya mencemari basis kode dan harus benar-benar dikelola secara eksternal oleh sistem kontrol sumber Anda.
Saya sepenuhnya tidak setuju dengan poster-poster lain di sini!
Komentar kode dengan referensi pelacakan dapat sangat membantu untuk pemrograman pemeliharaan.
Jika saya melacak bug dan mendekati area kode, untuk melihat bahwa itu baru saja diubah dan memiliki tautan ke konteks perubahan adalah pengiriman yang baik.
Ya, kami memiliki kontrol kode sumber, tetapi bisa sangat lambat untuk memeriksa file dan modul secara individual. Anda ingin hal-hal ini melompat keluar untuk Anda untuk perubahan terbaru.
Saya mungkin akan mencela mereka karena saya melihat yang lama di basis kode, tetapi ada sedikit sisi buruk untuk mempertahankan yang lebih baru dan banyak waktu pengembang yang berpotensi disimpan jika Anda menggunakannya dengan cerdas.
Saya benar-benar berpikir ini sedikit referensi ke sistem pelacakan bug Anda lebih disukai daripada komentar rinci dalam kode.
git gui blame <filename>memberikan GUI yang sangat cepat untuk menelusuri sejarah kode jika Anda menggunakan git. Menggunakan alat untuk menggabungkan komentar kode dengan riwayat memungkinkan dokumentasi yang lebih baik untuk kode daripada komentar inline yang pernah ada. Artinya, jika Anda repot-repot menulis pesan komit yang baik (pesan komit yang baik harus kira-kira sama dengan pesan email yang menjelaskan mengapa tambalan itu harus diterapkan).
Jika Anda berlangganan kebijakan "Kode Bersih", maka Anda mungkin perlu bertanya pada diri sendiri apakah praktik yang baik untuk menambahkan komentar sama sekali. Jika kode hanya dapat diklarifikasi dengan komentar, maka tentu saja, tambahkan satu, jika tidak, Anda harus dapat dengan mudah memahami apa yang kode Anda lakukan hanya dengan membacanya (asalkan Anda menggunakan nama yang masuk akal untuk variabel, metode, dll.).
Terlepas dari pandangan pribadi Anda tentang apakah mengomentari adalah praktik yang baik atau tidak, komentar harus berisi informasi yang bernilai langsung ke kode yang merujuk komentar tersebut. Dalam kasus ini, pertanyaannya adalah apakah menambahkan nomor masalah menambah nilai pada kode. Masalah yang saya lihat dengan menambahkan nomor masalah adalah bahwa Anda dapat memiliki bagian kode yang mungkin banyak dimodifikasi untuk memenuhi beberapa masalah, dan setelah beberapa saat, mungkin mustahil untuk mengidentifikasi dengan benar perubahan mana yang terkait dengan masalah tertentu. Masalah-masalah selanjutnya, misalnya, mungkin memerlukan kode yang berkaitan dengan masalah-masalah sebelumnya untuk diolah kembali secara besar-besaran. Ini mungkin merupakan contoh ekstrem, namun hal ini menunjukkan bagaimana angka masalah dalam komentar dalam kode dapat menjadi sangat tidak berguna.
Jika Anda dapat menjamin bahwa situasi yang baru saja saya jelaskan tidak akan pernah terjadi, saya masih akan berargumen bahwa nomor masalah itu sendiri masih sangat tidak berguna tanpa deskripsi tentang apa masalahnya, namun, semua informasi ini benar-benar milik Anda. masalah sistem pelacakan dan harus digandakan. Tempat yang lebih baik untuk mencatat nomor masalah adalah di sistem kontrol versi Anda sebagai komentar komit. Keuntungannya adalah Anda dapat membandingkan versi dan melihat perubahan kode yang berkaitan dengan masalah tertentu, sementara nomor masalah itu sendiri memberi Anda pengenal yang diperlukan jika Anda ingin meninjau alasan perubahan dalam kode.
Dengan semua ini dalam pikiran, saya akan menyarankan bahwa itu bukan praktik yang benar-benar baik seperti menambahkan nomor masalah ke dalam komentar dalam kode Anda.
Saya pikir ini praktik yang baik untuk merujuk pada masalah untuk dibaca lebih lanjut, sambil memberikan penjelasan singkat dalam komentar itu sendiri.
Saya biasanya hanya menambahkan komentar jika ada sesuatu yang halus atau tidak intuitif dalam potongan kode itu. Karena beberapa masalah tidak dapat dijelaskan sepenuhnya dalam beberapa baris, dan saya tidak ingin menambahkan lusinan komentar, saya akan menambahkan komentar singkat yang menggambarkan apa yang ingin dicapai, dan merujuk ke masalah untuk detail.
Sebagai contoh:
// Verify MAC before checking the padding, to avoid padding oracle attacks
// See issue 123 for details
Di mana masalah 123 menjelaskan seperti apa serangan itu, dan mengapa kode baru itu kebal terhadap serangan itu.
Atau:
// Using foo's algorithm here, since it fits out usage pattern best
// Check issue 345 for a discussion of possible algorithms, and why foo was chosen.
Masalah utama dengan memasukkan nomor masalah ke sumber Anda adalah bahwa Anda sekarang memiliki referensi eksternal. Jadi, Anda harus yakin bahwa Anda tidak akan kehilangan masalah.
Memasukkan nomor masalah dalam pesan komit bisa sangat berguna ketika kode sumber Anda dihubungkan dengan integrasi berkelanjutan. Aplikasi seperti TeamCity akan mengeluarkan informasi itu dan memungkinkan pelaporan yang lebih baik.
Dengan kata di atas saya tidak yakin 100% menarik dari komentar kode. Menyertakan nomor masalah dalam kode berfungsi dengan baik jika nomor masalah tetap ada (mis. Anda tidak mengubah pelacak masalah) dan Anda tidak memiliki banyak masalah untuk proyek yang diberikan.
Mungkin lebih bermanfaat jika Anda menjelaskan masalah dan solusinya sehingga pengembang berikutnya tidak perlu mencari nomor masalah. Compiler atau minifier hanya akan menghapus komentar Anda sebelum kode dilepaskan ke wild sehingga seharusnya tidak ada dampak pada hasil akhir.