Apa cara terbaik untuk berkomentar dalam ulasan kode?

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.

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.

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.

Saya ingin menyampaikan maksud saya tanpa terlihat kasar.

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.

  Saya juga tidak ingin terlihat seperti saya mencoba 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 .

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.

Itu tergantung pada jenis masalah apa yang telah diperhatikan

• pemberitahuan copywrite yang hilang - masalah umum dan membosankan hanya komentar singkat yang menyatakan masalah tersebut dan beralih
• tempat di mana saya mungkin melakukannya secara berbeda - biasanya cenderung untuk mengajukan pertanyaan di sini daripada membuat pernyataan, kadang-kadang jawabannya akan membenarkan solusi asli kali lain tidak dan kemudian saya dapat membahasnya dengan lebih jelas.
• tempat-tempat di mana terdapat cacat yang jelas, misalnya Penimpaan yang setara yang dapat menumpuk arus - meraih pena merah - menandainya sebagai cacat dan menjadi sangat eksplisit mengapa rusak - juga memeriksa area serupa lainnya untuk memeriksa bahwa tidak ada masalah sistematis.

Dari pengalaman saya:

1. Selalu bawa pembuat kode bersama Anda saat meninjau kodenya. Lebih disukai kode diproyeksikan di papan tulis dan Anda berdua dapat melihat kode dengan jelas.

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

3. Minta dia untuk meninjau kode Anda dan menerima dan menyetujui poin yang valid dan memperbaikinya. Beri hormat untuk komentarnya dalam kode Anda dan dia akan secara otomatis menghormati komentar ulasan kode Anda.
4. Menangani di tingkat pengembang kecuali sangat penting atau lebih banyak waktu diperlukan untuk memperbaiki masalah ulasan kode. Jangan naik ke manajer untuk masalah sederhana jika kondisi hilang.
5. Lihat dengan perspektif "Belajar dari kode lain" alih-alih menunjukkan kesalahan dalam kode.
6. Selama sesi peninjauan kode, kutip kesalahan masa lalu yang telah Anda buat dan bagaimana tinjauan kode membantu Anda dan menghindari masalah produksi besar karena sepasang mata lain membantu Anda.
7. Jadilah rendah hati. Lebih banyak penghargaan dan lebih sedikit komentar kepadanya :) Anda akan belajar banyak selama pengkajian kode dan dia juga akan dengan senang hati menerima komentar Anda.