Apakah umumnya bermanfaat untuk memasukkan masalah JIRA dalam komentar kode?

8

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.

— Mr_Spock
sumber

duplikat agak terang-terangan Apakah itu praktik yang baik untuk mengomentari dengan nomor masalah?

— nyamuk

2

@gnat Itu bukan "terang-terangan", tapi terima kasih untuk referensi.

— Mr_Spock

1

satu keuntungan kecil adalah alat seperti IDE dapat dengan mudah membuat hyperlink ke tiket yang sesuai.

— axd

7

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.

//must log to the database instead of standard logging, 
//stupid requirement from those crazy DBAs!! see TKCT-1234

atau mungkin Anda juga memasang tautan

//work around stolen from this stackoverflow answer http://stackoverflow....

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:

"Tidak, aku tidak melakukan kesalahan, seseorang mengatakan kepadaku bahwa harus seperti ini. Lihat! Ini nomor tiket untuk membuktikannya!"

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.

— Ewan
sumber

1

Saya setuju. Ada kalanya saya mencari database pelacakan mundur tetapi tidak sering. Saya lebih suka memiliki informasi yang relevan dalam kode komentar hanya jadi itu di satu tempat, jadi saya tidak suka memasukkan nomor tiket untuk tiket yang dikerjakan. Di sisi lain, saya sudah terbiasa meninggalkan nomor tiket mendatang / masa depan di TODO yang mungkin saya tinggalkan dalam kode saat ini karena memberikan gagasan kapan TODO akan diselesaikan, dan jika seseorang datang kemudian dan menemukan TODO untuk tiket yang sudah ditutup, itu adalah bendera yang terlewat ketika tiket berikutnya berhasil.

— jia103

5

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 baik
Variasi lain dari jenis yang sama.

Jika 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 .

Referensi tiket memberikan keterlacakan untuk perubahan yang diperlukan untuk pekerjaan yang diminta
JIRA bukan satu-satunya alat pelacakan tiket yang mampu melakukan sinkronisasi ini.

Saya sangat merekomendasikan format komentar seperti berikut ini:

 DIGIT-827: We only need to use the following for V4 of the computation.

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.

— Berin Loritsch
sumber

Mengenai inisial / tanggal / uraian tentang perubahan komentar, sementara saya setuju bahwa mencari di repo lebih baik, saya ingin menunjukkan bahwa pada proyek terakhir saya mereka menyimpulkan bahwa header file standar kami dengan tahun hak cipta awal digabungkan dengan menjalankan riwayat perangkat lunak di header file adalah bukti yang cukup untuk menjaga hak cipta tetap terkini, jadi jika file sumber dimulai pada 2013 dan diperbarui hingga hari ini (2018), maka kebiasaan memperbarui header file membiarkan hak cipta berlanjut tanpa pekerjaan tambahan , meminimalkan kemungkinan penyimpangan.

— jia103

@ jia103, Tajuk hak cipta adalah masalah yang berbeda dengan mengomentari garis yang diubah pada tanggal ini dan itu menggunakan inisial seseorang yang mungkin atau mungkin tidak menjadi bagian dari tim saat ini. Satu adalah hal yang legal, yang lain adalah informasi berlebihan yang sederhana yang tidak memberikan konteks untuk memahami kode di sebelahnya.

— Berin Loritsch

2

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.

— bdsl
sumber

1

Masukkan masalah Jira dalam komentar komit, kemudian gunakan plugin untuk menautkan komit ke Jira yang sebenarnya.
Pesan komit kami mulai dengan:

JIRA: XBVS-1222 Fixes bugs...

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.

— bot_bot
sumber

1

Masalah Jira tunggal sama dengan cabang tunggal dan setiap komit diberi penjelasan dengan pengidentifikasi Jira untuk masalah tertentu, seperti yang Anda rekomendasikan. Saya telah menggunakan ini untuk waktu yang lama dan menggunakan git menyalahkan itu adalah cara yang bagus untuk melacak perubahan kode dan alasan mereka tanpa mencemari kode yang sebenarnya dengan komentar yang tidak berguna.

— Andy

1

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.

— mcknz
sumber