Bagaimana cara meyakinkan rekan dev saya untuk MAU menambahkan komentar ke kode sumber yang dilakukan?

Saya tahu bahwa Subversion (apa yang kami gunakan di tempat kerja) dapat dikonfigurasikan untuk memerlukan komentar saat melakukan, namun saya tidak dalam posisi yang kuat untuk mengaktifkannya. Saya tahu bahwa alasan saya berkomentar tentang komitmen saya adalah karena berguna, jika hanya sebagai pelari memori, untuk dengan cepat memahami alasan di balik komit. Namun, ini tampaknya tidak cukup untuk melawan dua tanggapan yang selalu saya dapatkan:

1. Butuh waktu terlalu lama dan saya hanya ingin memasukkan perubahan saya ke dalam repo.
2. Cukup mudah untuk hanya melihat perbedaan.

Saya bahkan menunjukkan kepada mereka nilai dari hanya memasukkan ID masalah JIRA dan bagaimana hal itu secara otomatis terkait dengan masalah ini, tetapi masih tidak ada dadu dengan mereka.

Yang terburuk, orang yang bisa menelepon ada di kemah yang sama: tidak mau repot dan tidak masalah dengan melihat perbedaan.

Saya tahu itu hal yang benar untuk dilakukan, tetapi bagaimana saya bisa membuat mereka melihat cahaya? Bahkan jika saya tidak dapat meyakinkan rekan dev saya, bagaimana saya bisa meyakinkan manajemen bahwa itu adalah hal yang benar untuk dilakukan untuk bisnis?

Fokus pada "Mengapa". Ini semua sangat baik melihat perbedaan dan melihat bahwa seseorang mengubah aliran logis dari bagian kode atau sesuatu seperti itu, tetapi mengapa mereka mengubahnya? Alasannya biasanya ada di tiket terkait (JIRA untuk Anda).

Mereka mungkin bertanya-tanya mengapa "Mengapa" itu penting tetapi dalam 2 tahun ketika Anda telah menangkap beberapa bug yang merupakan dampak dari perubahan itu, mengetahui mengapa itu dilakukan sangat penting untuk tidak hanya memperbaiki bug baru Anda, tetapi memastikan Anda tidak menyebabkan bug lama muncul kembali.

Ada juga alasan audit. Mengikat komit dan ID tiket membuatnya sangat mudah untuk mengatakan ok, kami mendorong keluar Versi 2, perbaikan ini cacat 23, 25, 26 dan 27 tetapi tidak ada komitmen terhadap cacat 24 sehingga masih beredar.

Buat mereka melakukan penggabungan dan menangani dukungan. Sekali lagi mungkin Anda tidak berada dalam posisi untuk melakukan ini, tetapi jika Anda menemukan diri Anda menjadi orang yang memecahkan masalah dari komit sebelumnya dengan sopan kirimkan ke pagar dan katakan. Saya tidak tahu apa yang Anda lakukan karena tidak ada komentar komit, Anda membuat perubahan ini dan Anda perlu mengetahuinya.

Juga untuk menggabungkan cabang. Tidak yakin apakah itu jatuh pada Anda atau tidak, tetapi itu adalah satu bidang yang saya temukan komentar bermanfaat.

Sekali lagi, bukan di kapal Anda, tetapi ketika saya mengelola tim perangkat lunak saya mengatakan kepada mereka jika mereka membuat komentar komit yang baik, saya akan menggunakan mereka dalam laporan status mingguan. Setelah itu saya mendapatkan komitmen yang sangat baik dan lebih mudah bagi saya untuk melacak apa yang terjadi sebagai manajer.

Kami memerlukan komentar lapor-masuk karena alasan yang sama seperti kami membutuhkan jeda baris dan jarak dalam kode kami. Untuk mempermudah penelusuran, pahami membaca dan memahami.

Kadang-kadang Anda perlu membandingkan, tetapi sering kali tidak. Memaksa para pengembang untuk membandingkan ketika yang mereka butuhkan hanyalah membaca 2-3 kalimat adalah buang-buang waktu saja. Saya heran mengapa mereka tidak melihat nilai waktu pengembang.

• Berikan contoh yang baik. Buat pesan komit Anda sendiri sebagai contoh kegunaan. Masukkan referensi ke sistem lain apa pun yang digunakan tim Anda untuk mengelola cerita dan cacat. Letakkan pernyataan singkat yang merangkum perubahan, dan penjelasan yang baik tentang mengapa perubahan itu perlu dan bukan sesuatu yang lain dalam setiap pengajuan.
• Setiap kali kurangnya pesan komit yang layak menyebabkan Anda bekerja ekstra, ajukan pertanyaan ke pengirim. Bersikaplah gigih dengan ini (tapi bukan brengsek).
• Jika tidak melampaui peran Anda, tulis skrip yang mengirim changelog harian menggunakan pesan komit. Ini akan memberikan kredibilitas pada argumen Anda bahwa pesan yang bermanfaat memiliki manfaat di luar penjelajahan melalui revisi. Ini juga dapat membantu membuat manajemen berada di pihak Anda, karena mereka akan melihat dari hari ke hari apa yang terjadi.
• Identifikasi sekutu Anda. Semoga ada setidaknya satu orang lain yang setuju dengan Anda (mungkin dengan diam-diam tidak setuju). Temukan orang itu atau orang-orang itu dan yakinkan mereka lebih jauh sehingga Anda tidak berdiri sendiri.
• Ketika kesempatan untuk menyebutkan bagaimana pesan komit yang baik telah menghemat waktu Anda (atau pesan yang buruk menghabiskan waktu Anda) hadir, manfaatkanlah.

Jangan takut untuk menjadi roda melengking. Melawan kebiasaan buruk orang lain sering kali merupakan perang gesekan.

Ini harus menjadi salah satu pertanyaan paling aneh yang pernah saya dengar. Orang-orang menghabiskan berjam-jam atau bahkan berhari-hari memperbaiki sesuatu dan tambahan 2 detik untuk mengetikkan pesan komit terlalu lama ?! Saya harus mengatakan bahwa saya akan khawatir tentang bekerja dengan orang-orang yang picik. Mereka jelas tidak menggunakan alat mereka bahkan untuk mendekati potensi penuh mereka.

Ini contoh dari review kode yang saya ikuti minggu lalu. Perangkat lunak kontrol versi kami tidak menyimpan sejarah di seluruh penggabungan, jadi untuk perubahan yang lebih lama Anda harus menemukan cabang persisnya dibuat, jika tidak, pesan komit hanya menunjukkan sesuatu seperti "digabung dari cabang Y." Cabang Y mungkin menunjukkan "digabung dari cabang Z," dan cabang beberapa tingkat bersarang lebih dalam sebenarnya memiliki pesan komit nyata.

Seorang karyawan baru tidak tahu bagaimana melacak sejarah dengan benar, yang berarti ia pada dasarnya bekerja hanya dengan para diff. Dia melihat beberapa kode komentar terkait dengan bug yang dia lacak. Ketika dia membatalkan komentar kode, bug-nya hilang. Dia berasumsi seseorang telah berkomentar kode selama debugging dan keliru memeriksanya.

Itu tidak terasa benar untuk beberapa dari kami selama peninjauan kode, jadi saya melacak pesan komit yang sebenarnya dan menemukan ada alasan yang sah untuk menghapus kode itu setahun yang lalu. Karyawan baru dapat memperbaiki kodenya untuk memperbaiki bug yang baru ditemukan tanpa memperkenalkan yang lama.

Ada cara yang lebih baik untuk menghindari memperkenalkan jenis regresi tersebut, seperti tes unit menyeluruh, tapi entah bagaimana saya tidak melihat orang yang tidak bisa repot-repot dengan pesan komit 2 detik "buang-buang" waktu pada pengujian unit.

Saya memiliki masalah yang sama persis di sini, jadi saya menambahkan kait pra-komit ke Subversion sehingga tidak akan menerima komit yang tidak dimulai dengan nomor Kisah Pengguna (beberapa pola dasar yang cocok dengan format yang diharapkan).

Tidak ada yang menghentikan mereka memasuki 000-0000, tetapi sekali saja idiot pengganggu akan membuat nomor ketika mereka memiliki nomor yang bisa diterima di sana.

Saya melakukan ini setelah menghabiskan berhari-hari mencoba mencari yang membangun serangkaian cerita pengguna masuk ke. Ya itu untuk berurusan dengan kegagalan proses di tempat lain, tapi itu masih informasi yang sangat berharga untuk dilacak.

Komentar komit yang baik seperti dokumentasi yang bagus, cache untuk otak Anda yang lambat dan tidak berfungsi, atau cache hasil dari setiap debugging panjang / analisis masalah / investigasi.

Misalnya setiap kali Anda menghabiskan waktu mencari sesuatu, seperti debugging, menganalisis log atau apa pun, temuan dan hasil Anda sangat berharga. Tentu saja sebagian besar tugas dapat diulang, tetapi mungkin perlu waktu. Jadi, Anda harus selalu mendokumentasikan hasil Anda.

Namun, dokumentasi membutuhkan waktu dan kadang-kadang dirasakan tidak perlu, seperti "kami hanya perlu melakukan ini sekali, jadi mengapa menuliskannya". Tidak apa-apa, tetapi begitu Anda melakukan hal yang sama untuk kedua kalinya karena Anda tidak mendokumentasikan hasil pertama kali, maka tentu saja pintar untuk mendokumentasikan hasil.

Jadi, jika kolega Anda merasa terlalu sulit untuk menambahkan komentar komit, misalnya setidaknya menunjuk ke kasus Jira / Tiket yang mereka selesaikan, yah, maka mereka mungkin termotivasi oleh tekanan untuk terus-menerus menanggapi pertanyaan mengenai alasan masing-masing changeset.

Menurut pendapat saya, dokumentasi harus dibuat sebagai fungsi informasi yang diminta. Misalnya, korespondensi surat adalah sistem dokumentasi yang cukup bagus. Pertanyaan menerima jawaban yang nantinya bisa diambil, begitulah cara kerja milis dan forum dalam praktik sebagai basis pengetahuan.

Sayangnya, tempat saya bekerja, email dihapus secara otomatis setelah 3 bulan, jadi itu tidak selalu berhasil dalam praktik.

Mencari pengampunan, bukan izin.

Meski kasar, saya melakukan ini. Saya memiliki perpecahan 50/50 antara orang-orang yang mendukung dan orang-orang yang menentang, kebanyakan dari mereka adalah tingkat yang sama dengan saya dalam kelompok. Argumennya adalah "Saya tidak bisa diganggu" dan "Apa gunanya?". (Keduanya menunjukkan sikap apatis dan kemalasan, bukan kekhawatiran asli).

Saya menambahkan kait pra-komit yang hanya mengukur panjang tali dan memberikan pesan yang sedikit lucu sebelum menolaknya. Saya memasukkan nama saya ke dalam pesan sehingga tanggung jawab untuk "kemarahan ini" sudah jelas. Tentu saja, "oposisi" dapat dengan mudah menghapusnya, tetapi menggali skrip akan membutuhkan lebih banyak upaya daripada menambahkan satu komentar lagi!

Selama seminggu saya mendapat pesan yang ditambahkan seperti * * (sumpah serapah dihapus) atau kjhfkwhkfjhw. Setelah itu, pesan dasar mulai muncul.

Setahun kemudian dan orang-orang skeptis menggunakan komentar yang kejam dan benar-benar mengakui betapa piciknya mereka. Saya tidak pernah bisa mendapatkan konsensus, tetapi saya pasti mendapat pengampunan dan mungkin kredibilitas. Berhasil, orang menggunakannya.

Jika Anda ingin bersikap lebih ramah (atau merasa bahwa Anda akan mendapat masalah), mintalah izin untuk menambahkan kait komit untuk masa percobaan. Katakan bahwa jika orang tidak menyukainya dalam 2 minggu atau 4 minggu, Anda akan mengeluarkannya. Kemungkinannya adalah, mereka akan kehilangan minat ... atau tumbuh untuk menyukainya.

Saya biasanya meyakinkan orang melalui:

• dialektika dengan alasan pendukung yang baik
• memimpin dengan memberi contoh
• erosi

Jika saya ingin tim kami melakukan sesuatu yang cukup buruk saya akan terus mengganggu sampai saya mendapatkan apa yang saya inginkan. Saya mencoba mengganggu saat-saat di mana saya bisa menunjukkan bahwa kita bisa menghemat waktu / uang seandainya kita sudah melakukan X.

Alasan bagus tambahan untuk berkomentar:

• Menghasilkan ChangeLog secara otomatis dari komentar.
• Jejak audit untuk perbaikan bug, penambahan fitur. Ini berguna baik di dalam maupun di luar tim.
• Jadikan surat komit lebih berguna.
• Hentikan saya untuk bertanya kepada pengembang apa yang dilakukan komit X (setelah hampir setiap komit).

• Periksa log SVN Anda untuk sesuatu yang tidak jelas yang dibuat 6 bulan lalu.
• Ajukan beberapa pertanyaan tentang hal ini tanpa memberi tahu kapan hal itu dilakukan
• ???
• Keuntungan

Bagaimana Anda membuat mereka ingin menambahkan komentar yang bagus?

Dari pengalaman dengan seorang rekan saya baru saja. Pada akhir proyek, kami harus menulis dokumen ringkasan dari semua perubahan yang dilakukan di seluruh proyek. Karena tidak membuat catatan komit yang baik, kolega saya menganggap tugas ini agak menghabiskan waktu, dan sekarang beralih untuk membuat komentar yang cukup panjang dengan setiap komit.

Jadi - solusi - satu solusi bisa membuat pengembang menulis ringkasan dokumen di akhir proyek yang merinci perubahan apa yang dibuat untuk file apa, file apa yang ditambahkan / dihapus dan mengapa.

Ajukan ini kepada manajemen di balik pintu tertutup:

Skenario kasus terburuk terjadi: Semua pengembang tingkat senior berjalan keluar.

Ketika perusahaan berebut untuk mengisi kursi pengembang yang kosong, tim manajemen ditugaskan untuk mengkomunikasikan status sistem kepada klien.

Tanyakan kepada mereka apa yang menurut mereka akan membuat pekerjaan mereka lebih mudah dalam merekonstruksi sejarah aplikasi:

Membaca komitmen bahasa Inggris yang jelas menggambarkan perubahan keadaan sistem?

Atau apakah mereka lebih suka melihat perbedaan kode dan mencari tahu sendiri?

Saya kira salah satu cara untuk meyakinkan mereka adalah dengan benar-benar mengalami rasa sakit yang Anda rasakan.

Sebagai contoh, katakanlah mereka sedang mengerjakan masalah berikut: Mereka memiliki bug yang, entah bagaimana muncul ketika perbaikan bug lain untuk kode yang sama (oh ironi) diimplementasikan. Untuk dapat mencari ini dari hanya mencari melalui pesan komit akan menjadi besar (dan dengan demikian mencari tahu siapa yang menulisnya).

Cara lain adalah dengan menjelaskan kepada mereka bahwa pesan komit dapat bermanfaat untuk memberikan petunjuk mengapa sesuatu diterapkan dengan cara tertentu. Bahkan jika pesan komit hanya mengatakan "fitur X", Anda masih bisa mendapatkan petunjuk yang mengimplementasikannya, sehingga Anda tahu siapa yang harus diajak bicara.

Namun, ini tampaknya tidak cukup untuk melawan dua tanggapan yang selalu saya dapatkan:

1. Butuh waktu terlalu lama dan saya hanya ingin memasukkan perubahan saya ke dalam repo.
2. Cukup mudah untuk hanya melihat perbedaan.

Sudahkah Anda mencoba melempar tantangan ke sesama pengembang sehingga mereka mendapat manfaat lain dari memberikan komentar? Orang dapat melihat ini dari salah satu dari beberapa sudut pandang yang berbeda:

1. Meningkatkan permainan mereka - Ini bisa menjadi perspektif yang lebih sulit untuk diambil tetapi idenya di sini adalah bahwa mereka melakukan ini selama beberapa waktu dan membiasakan diri dengan ide sehingga kebiasaannya akan memakan waktu lebih lama untuk pergi ke arah lain. Poin lain di sini adalah berapa banyak pengawasan akan mendapatkan komentar? Jika Anda ingin cerita pendek di komentar saya bisa mengerti maksud mereka.
2. Mensubsidi perubahan - Di sinilah Anda akan mengadakan semacam kontes sebagai cara untuk menerima pembelian awal untuk mencoba ini atau menawarkan semacam insentif lain agar perubahan dilakukan untuk sementara waktu.

Hal lain yang perlu dipertimbangkan adalah seberapa baik Anda tahu apa yang dikelola sesama pengembang di tempat Anda bekerja? Jika mereka mencoba menyelesaikan 10 hal kemarin, saya bisa mengerti bahwa mereka mungkin tidak ingin mengubah apa yang mereka lihat sebagai sesuatu yang sudah berfungsi. Apakah Anda mencoba memberi tahu mereka, "Tidak, ini tidak berhasil?" Jika demikian, maka saya dapat melihat bagaimana mereka mungkin sedikit defensif atau agresif dalam hal ini. Jika Anda mencoba memberi tahu mereka, "Meskipun ini mungkin berhasil, ada alternatif yang mungkin lebih baik ..." maka Anda mungkin memiliki kesempatan. Memiliki sikap "Lebih suci daripada kamu" di sini tidak akan membantu Anda, IMO.

Cara lain untuk melihat hal ini adalah sebagai cara untuk pengembang (s) yang terlibat untuk tumbuh karir mereka - mereka harus memiliki satu dokumentasi dari pekerjaan mereka.

Selain poin-poin lain yang diangkat dalam artikel yang direferensikan di atas, ada kemampuan untuk dapat meninjau perubahan kode untuk mengetahui di mana / kapan / mengapa perubahan dilakukan. Itu bisa sangat penting ketika melacak bug yang sulit dipahami.

Setelah Anda meyakinkan mereka bahwa penting untuk mengomentari komit Anda, Anda dapat membuat skrip yang memaksa komentar pada komit, jika tidak maka akan gagal. Anda bahkan dapat menentukan karakter minimum untuk memastikan komentar yang bermakna. Ini akan membantu mereka "mengingat".

Namun, penting mereka memahami Mengapa seperti yang dikatakan @Kevin, atau mereka hanya akan menambahkan komentar acak apa pun.

Apakah Anda memiliki ulasan kode? Satu hal yang dapat membantu adalah melembagakan aturan bahwa komit atau penggabungan harus dilihat dan disetujui oleh pengembang lain. Maka jika Anda adalah peninjau, Anda harus meminta pengembang membuat komitmen untuk menjelaskan kepada Anda apa yang dia lakukan. Begitu dia melakukannya, Anda harus memintanya untuk mengetik di komentar apa yang baru saja dia katakan kepada Anda. Seringkali ketika seseorang tidak dapat menjelaskan perubahan yang dibuat secara koheren, itu berarti bahwa perubahan itu seharusnya tidak dilakukan sejak awal.

Namun saya harus mengatakan, bagaimana orang bisa menolak sesuatu yang jelas bermanfaat seperti berkomentar? Tidak butuh waktu lama, dan ini menghabiskan waktu dengan baik. Menulis komentar memaksa Anda untuk berpikir tentang apa yang baru saja Anda lakukan. Bahkan dapat menyebabkan Anda melihat perbedaan untuk memastikan Anda memang telah melakukan apa yang Anda pikir telah Anda lakukan, dan bahwa Anda belum melakukan hal bodoh.

Ketika Anda tidak menulis komentar, Anda menjadi ceroboh dan tidak disiplin. Dan jika Anda bersikeras bahwa Anda tidak harus diminta untuk menulis komentar, maka Anda sengaja lalai.

Beri tahu mereka bahwa ini satu-satunya cara untuk berkesempatan menjaga kekacauan prosedural Anda dari 50.000 metode garis, kemudian pertimbangkan untuk menulis kode yang lebih baik dan lebih eksplisit di masa depan sehingga Anda tidak perlu berurusan dengan banyak komentar tidak berguna yang membengkak berdasarkan kode Anda.

Ini adalah item perubahan proses: Minta manajer menetapkan kode yang dikembangkan oleh "x" menjadi "Y" untuk pemeriksaan jaminan kualitas pada kode saja, termasuk QA komentar.

Di organisasi saya sendiri, pengembang tidak diizinkan untuk melakukan QA akhir dari kode mereka sendiri dan memeriksanya, ini harus dilakukan oleh pengembang lain. Bagian dari QA Check adalah komentar, jadi tidak ada komentar, tidak ada check-in. Kami melakukan banyak pekerjaan kontrak di mana "seni" kami sebenarnya adalah kekayaan intelektual kontraktual orang lain, sehingga orang lain harus dapat memahami dan memanfaatkan kode kami. Juga, ada saat-saat ketika proyek kembali kepada kami setelah jeda yang panjang dan kami harus dapat mengambil kode 18-24 bulan kemudian dan memahami mengapa, di mana dan bagaimana kami tiba di artefak kode di depan kami. Ini memberikan motivasi mementingkan diri sendiri untuk menulis komentar komit.

Tanyakan dan dapatkan rekan pengembang Anda untuk melakukan beberapa penggabungan dan untuk mencari riwayat dan membandingkan beberapa file dari sejarah.

Kemungkinannya adalah mereka akan meminta Anda untuk memberikan komentar pada hari berikutnya dan seterusnya.

Berikut ini beberapa saran:

1. Jangan mencoba mengubah dunia. Anda akan gagal.
2. Sebaliknya, Anda harus menyadari bahwa setiap orang bekerja dengan cara yang sedikit berbeda. Tidak ada satu ukuran yang cocok untuk semua orang.
3. membutuhkan beberapa langkah spesifik untuk proses kerja orang adalah sangat jahat. Mengubah proses ini membutuhkan waktu 10 tahun. Anda meminta mereka untuk melakukan ini sebelum batas waktu berikutnya.
4. Bahkan perubahan proses sederhana dapat memakan waktu lama.
5. Beberapa komentar kecil tentang komitmen terlalu kecil untuk mengubah proses ini.
6. Anda dapat menganggap mereka melakukan pekerjaan yang berkualitas, tetapi harus memberikan kebebasan yang cukup untuk memilih langkah-langkah itu sendiri. Beberapa langkah memberatkan mungkin tidak diperlukan untuk pengembang berpengalaman.
7. Jika Anda mengasuh pemula, maka proses yang lebih kuat mungkin diperlukan, tetapi pengembang yang berpengalaman tidak harus berurusan dengan omong kosong.
8. Memaksakan pembatasan kejam tentang bagaimana pekerjaan harus dilakukan tidak pernah akan berhasil, itu hanya dapat memperlambat orang (mungkin bagus jika mereka terlalu cepat)
9. Ada banyak orang yang berpikir bahwa jalan mereka adalah satu-satunya cara yang tepat untuk melakukan sesuatu. Semoga Anda bukan salah satu dari mereka.

Jika kontrol sumber Anda memprovokasi hal itu, aktifkan komentar wajib untuk mencegah komitmen yang tidak dikomentari. Cukup sederhana dan semua orang akan segera menyadari bahwa 5 detik mengetik komentar tidak menyakitkan.

Tetapi komitmen yang tidak dikomentari adalah salah satu negatif terkecil yang ada. Saya telah menjadi bagian dari banyak proyek yang sukses di mana tidak ada komit tunggal berkomentar. Jangan bawa celana dalam Anda banyak di atasnya.