Sesekali, saya meninggalkan komentar seperti
# We only need to use the following for V4 of the computation.
# See APIPROJ-14 for details.
atau
# We only need to use the following for V4 of the computation.
# See https://theboringcompany.atlassian.net/browse/DIGIT-827 for details.
Perhatian utama saya dengan melakukan itu adalah bahwa hal itu meningkatkan ketergantungan kita pada JIRA, sehingga komentar-komentar itu akan sepenuhnya diperdebatkan jika kita pindah ke sistem manajemen proyek lain. Meskipun saya tidak melihat hal itu terjadi dalam waktu dekat, saya tetap waspada dengan peningkatan kopling komponen organisasi (dalam hal ini: kode, repositori kode dan sistem manajemen proyek).
Namun , saya melihat manfaat memiliki referensi untuk keputusan desain yang terdokumentasi dan inspirasi fitur di seluruh basis kode. Sejauh yang saya tahu, manfaatnya
- jalur yang jelas untuk keputusan desain, yang membantu dengan debugging dan meningkatkan pada segmen tertentu dari kode asing,
- lebih sedikit komentar multi-baris, yang membuat kode tampak lebih bersih / kurang menakutkan bagi kontributor baru,
- jalur yang jelas untuk (berpotensi) pemangku kepentingan teknis dan non-teknis saat ini, dan
- penurunan jumlah "mengapa ini di sini" pertanyaan karena yang disebutkan di atas.
Jawaban:
Saya akan mencoba menghindari komentar semacam itu. Meskipun saya pikir ada tempat untuk mereka di mana Anda memiliki persyaratan yang sangat menjengkelkan. Yang tanpa, siapa pun mungkin ingin memperbaiki kode. misalnya.
atau mungkin Anda juga memasang tautan
Tetapi tidak untuk alasan Anda menyatakan peningkatan kopling. Bahkan saya memberi nama semua cabang fitur saya sesuai dengan tiketnya. Jadi dimungkinkan untuk melacak semua pekerjaan kembali ke tiket jika diperlukan, meskipun riwayat komit. (Anda juga dapat melakukan beberapa hal tutup otomatis yang pintar jika Anda merasa pintar)
Tidak, saya tidak khawatir tentang perubahan sistem tiket. Tapi apa yang saya sadari adalah bahwa sangat langka bagi siapa pun untuk melihat kembali tiket begitu mereka selesai.
Jadi komentar ini berguna karena dikatakan sebagai pengganti Anda di masa depan:
Tetapi mereka tidak akan pergi dan memeriksa tiket itu. Hidup ini terlalu singkat.
Jika Anda terbiasa menaruh komentar referensi tiket di mana-mana, maka mereka kehilangan dampaknya. Alih-alih menjadi bendera "baca ini, ini sangat penting!" mereka hanya menjadi berantakan.
Secara umum persyaratan harus dicatat melalui media tes. Jika tes lulus, maka persyaratan harus dipenuhi, kita tidak perlu khawatir tentang bagaimana mereka awalnya dinyatakan.
sumber
Untuk Komentar Kode, hanya ada sedikit kegunaannya. Untuk komentar kontrol versi, mereka sangat berguna untuk alasan yang diuraikan di bawah ini.
Kode komentar harus benar-benar digunakan untuk membantu memahami maksud dari hal-hal rumit.
Jenis komentar kode yang buruk:
Updated EHS 10/24/2015- jika saya ingin tahu itu, saya akan menggunakan kontrol versi untuk menemukan siapa yang menulis baris mana.For spec 0.4- itu bisa menjadi bagian dari komentar komit, tetapi itu tidak membantu saya memahami kode lebih baikJika komentar kode ada, mereka harus membantu memahami bagaimana blok kode berhubungan dengan domain bisnis.
Jika JIRA dan kontrol versi Anda ditautkan maka ya mereka masuk akal untuk pesan Komit .
Saya sangat merekomendasikan format komentar seperti berikut ini:
JIRA dan hampir semua alat dengan integrasi ini cukup pintar untuk mengenali nomor tiket dan menghubungkannya dengan tiket yang sedang diselesaikan. Itu berarti URL lengkap tidak diperlukan . Ini juga berarti bahwa Anda bisa mendapatkan manfaat dan memberikan komentar yang bermakna untuk komit tertentu semua dalam satu baris.
Saat melihat tiket di JIRA, Anda akan melihat daftar perubahan dengan semua komentar sesuai dengan deskripsi, dll.
sumber
Ya, tetapi hanya dalam kasus yang jarang.
Secara umum saya membayangkan sebagian besar kode akan ditulis sehubungan dengan tiket JIRA, jadi saya tidak akan secara rutin berkomentar dengan id tiket - itulah alasan git. Tetapi dalam beberapa kasus kode mungkin berlawanan dengan intuisi - mungkin cara yang paling jelas untuk menulis kode tidak bekerja dan ada beberapa diskusi tentang mengapa tidak pada tiket. Dalam hal ini saya akan mempertimbangkan untuk menambahkan komentar dengan referensi tiket.
Jika salah satu bagian dari kode perlu mengatasi bug yang diketahui di bagian lain maka saya juga akan mempertimbangkan untuk menambahkan referensi tiket.
Saya tidak berpikir ini mengikat Anda terlalu erat ke JIRA, seolah-olah Anda ingin bermigrasi dari JIRA ke sistem alternatif, Anda dapat mengekspor masalah JIRA Anda sebagai CSV dan mengimpornya ke sistem lain. ID masalah mungkin berubah selama proses itu tetapi Anda harus dapat menyimpan ID tiket JIRA di suatu tempat di tiket yang diimpor.
sumber
Masukkan masalah Jira dalam komentar komit, kemudian gunakan plugin untuk menautkan komit ke Jira yang sebenarnya.
Pesan komit kami mulai dengan:
Misalnya, kemudian kaitkan antara bitbucket dan jira tautan komit ke jira. Maka mudah untuk melihat Jira yang terkait dengan itu di gerhana misalnya, dengan mengklik kanan pada nomor baris dan memilih "Tampilkan riwayat revisi". Saya pikir itu disebut demikian. Nomor masalah dan komentar Jira Anda akan disorot pada kolom nomor baris, dan melayang dengan mouse akan memberi Anda detailnya.
sumber
Ini tentu bukan praktik yang mengerikan untuk memasukkan masalah JIRA dalam komentar kode, tetapi teknik ini secara ketat / manual memasangkan dua masalah yang berbeda (masalah dan kode), dan dapat memerlukan pembaruan untuk beberapa sistem / lokasi (JIRA, di mana pun di sumber masalah disebutkan, riwayat kontrol versi).
Komentar kode secara umum bermasalah karena sering tidak diperbarui.
Pendekatan yang lebih baik akan menemukan beberapa cara untuk mengintegrasikan sistem pelacakan masalah Anda dengan sistem kontrol versi Anda, sehingga kedua masalah tersebut dapat dipertahankan secara terpisah, secara otomatis.
sumber