Tim saya baru saja mulai menggunakan crucible / fisheye untuk memulai ulasan kode setiap kali salah satu dari kami memeriksa sesuatu. Hanya ada 3 dari kami, dan kami masing-masing didorong untuk meninjau kode dan meninggalkan komentar sesuai keinginan kami.
Pertanyaan saya adalah, bagaimana cara terbaik memberikan komentar pada satu baris kode yang saya lihat ada masalah? Saya ingin menyampaikan maksud saya tanpa terlihat kasar.
Saya tidak ingin terlihat seperti sedang naik kuda dan berkata, " Saya sudah melakukannya dengan cara ini ... dan saya juga tidak ingin terlihat seperti saya berusaha bersikap otoritatif dan mengatakan sesuatu seperti " Ini harus dilakukan dengan cara ini ... " tetapi saya masih perlu menjelaskan bahwa apa yang mereka lakukan tidak terlalu baik.
Untuk Memperjelas: Ini adalah sumber yang sangat bagus untuk apa yang seharusnya saya cari untuk mengomentari: Apakah ulasan kode bersifat subyektif atau objektif (dapat diukur)? , tapi saya mencari cara mengomentarinya.
sumber
Jawaban:
Yah saya cenderung membuat komentar di beberapa bidang umum dan masing-masing jenis mungkin ditangani secara berbeda.
Diperlukan perubahan. Ini adalah jenis perubahan di mana saya menunjukkan bahwa kode tidak memenuhi persyaratan fungsional atau tidak berfungsi dan harus diperbaiki sebelum didorong ke produksi. Saya cenderung sangat mudah dalam komentar ini. Persyaratan mengatakan ..., ini tidak melakukan itu. Atau ini akan gagal jika nilai yang dikirim adalah nol (terutama ketika Anda tahu bahwa kasus akan terjadi berdasarkan data yang akan dikirim).
Lalu ada komentar "ini berhasil tetapi di sini ada cara yang lebih baik untuk mencapai itu". Anda harus lebih lembut dalam hal ini dan melakukan lebih banyak promosi penjualan. Saya mungkin mengatakan bahwa saya akan melakukan ini sebagai gantinya karena cenderung berkinerja lebih baik (saya biasanya meninjau kode SQL di mana kinerja sangat penting). Saya mungkin menambahkan beberapa detail tentang mengapa itu adalah pilihan yang lebih baik seperti yang akan saya lakukan dalam menjawab pertanyaan tentang Stack Overflow. Saya mungkin menunjukkan bahwa tidak perlu mengubah ini untuk kode khusus ini, tetapi untuk mempertimbangkan perubahan dalam pengkodean di masa depan. Pada dasarnya dengan jenis komentar ini saya mendidik orang-orang dengan pengalaman yang kurang tentang apa yang mungkin bekerja lebih baik.
Lalu ada komentar "ini berhasil tetapi kami melakukan hal-hal seperti ini". Ini mungkin juga akan diperlukan perubahan. Ini akan mencakup komentar tentang standar perusahaan atau arsitektur yang kami harapkan mereka gunakan. Saya akan merujuk dokumen standar atau arsitektur dan memberi tahu mereka untuk memperbaikinya. Komentar akan langsung tetapi netral, tidak ada dan sebagainya atau nama variabel tidak sesuai dengan standar penamaan atau hal-hal yang serupa. Misalnya, arsitektur kami untuk paket SSIS memerlukan paket untuk menggunakan basis data metadata kami untuk menyimpan informasi tertentu tentang paket dan membutuhkan pencatatan khusus. Paket akan bekerja tanpa hal-hal ini tetapi diperlukan untuk alasan perusahaan (kami perlu melaporkan tingkat keberhasilan impor misalnya atau menganalisis jenis kesalahan yang kami terima.)
Satu hal yang tidak ingin Anda lakukan dalam komentar ulasan kode adalah menyerang seseorang secara pribadi. Ini juga dapat membantu jika Anda menemukan sesuatu yang mereka lakukan dengan baik dan menunjukkan bahwa itu baik. Kadang-kadang saya belajar sesuatu yang baru dari ulasan kode dan jika saya melakukannya saya memberi tahu orang itu.
sumber
Jika kode mengikuti standar pengkodean Anda, tetapi Anda akan melakukannya dengan cara yang berbeda Anda harus bertanya pada diri sendiri apakah yang mereka lakukan salah.
Jika tidak ... itu hanya bukan bagaimana Anda akan melakukannya dan Anda tidak bisa meninggalkannya, coba tanyakan saja 'Mengapa Anda melakukannya dengan cara ini alih-alih seperti itu?' Kemudian Anda membuat mereka memenuhi syarat mengapa mereka melakukannya dengan cara yang mereka lakukan tanpa mengatakan 'Saya akan melakukannya dengan cara ini dan Anda juga harus ...'
Anda mungkin juga belajar sesuatu dalam proses itu.
sumber
Jangan bingung kesederhanaan dengan menjadi abrasif. Ketika ada masalah, dokumentasikan dengan cara yang bisa dipahami oleh siapa pun yang memperbaikinya. Tetap berpegang pada fakta dan jangan menulis esai. Yakni:
Ini akan menyebabkan frobnitz tidak berfungsi ketika fooble berada dalam 5 kerutan faktor snorgatz.
Konvensi mapan untuk melakukan ini adalah memanggil fazzatz () dengan Squidge yang baru diinisialisasi. Jadikan ini sebagai metode sehingga selalu terjadi dengan cara yang sama dan tidak diduplikasi.
Tujuan mengkaji kode adalah untuk menempatkan sepasang mata yang kedua, biasanya lebih berpengalaman, untuk menemukan masalah. Jika Anda berada dalam posisi memberikan penilaian pada pekerjaan orang lain dan ada alasan yang sah untuk mengatakan sesuatu tidak baik, Anda akan mengabaikan tanggung jawab Anda sebagai peninjau jika Anda tidak.
Akan ada perbedaan pendapat, dan itu adalah peluang bagi peninjau dan yang ditinjau untuk mempertahankan posisi mereka. Jika Anda adalah teman sebaya dan mencapai jalan buntu, temukan seseorang yang senior untuk memutuskan hubungan.
sumber
Itu tergantung pada jenis masalah apa yang telah diperhatikan
sumber
Dari pengalaman saya:
Selalu bawa pembuat kode bersama Anda saat meninjau kodenya. Lebih disukai kode diproyeksikan di papan tulis dan Anda berdua dapat melihat kode dengan jelas.
Selamat mengobrol. Hargai bagian baik dari pengkodean. Katakan padanya bahwa "ini yang terbaik yang pernah saya lihat" jika Anda melihat beberapa bagian yang baik dalam kode.
sumber