Saya menemukan dokumen dengan peraturan dan rekomendasi tentang proses tinjauan kode dalam perusahaan. Saya memutuskan bahwa informasi yang berguna tersebut harus dibagikan kepada dunia luar. Dengan restu dari
penulis, saya menerbitkan karya itu.
Sebagian besar aturan ini bersifat nasihat dan harus dipandu terutama oleh akal sehat, dan bukan ketaatan buta.
Ketentuan Umum
- Di hh.ru, ulasan dilakukan dalam format permintaan tarik di Github.
- Tinjau dan tarik permintaan diperlukan, bahkan jika dalam kerangka tugas satu baris atau satu karakter dalam kode diubah.
- Setiap tugas harus memiliki setidaknya satu peninjau yang bertanggung jawab, itu ditunjukkan dalam tugas sebagai peninjau dan bertanggung jawab atas kode, seperti penulis. Tidak dilarang dan didorong untuk berpartisipasi dalam peninjauan orang lain.
- Tanggung jawab melakukan tugas melalui tinjauan berada di tangan penulis tugas.
- Setiap perubahan setelah tinjauan, seperti revisi selama pengujian, juga harus dipratinjau.
Tinjau Tujuan
- Diseminasi pengalaman dan pengetahuan antar pengembang.
- Dukungan untuk prinsip - perubahan tidak boleh memperburuk kode yang ada, mereka harus memperbaikinya.
- Koreksi kesalahan dalam logika dan kesalahan yang terkait dengan keamanan, penanganan pengecualian yang benar.
- Meningkatkan kualitas kode, rawatan, dan arsitektur proyek.
- Meningkatkan keterbacaan kode.
- Meningkatkan cakupan pengujian dan pengujian pada tingkat yang tepat.
- Memperbaiki dokumentasi.
- Kepatuhan terhadap perubahan dengan persyaratan dalam tugas.
- Pencegahan utang teknis atau pajak teknis.
- Desain API yang bijaksana, di mana API adalah modul apa pun dengan antarmuka eksternal. Misalnya, bahwa sumber daya dalam layanan memiliki URL yang dipikirkan dengan matang, format JSON yang nyaman, kode respons yang benar dalam berbagai kasus, dan sebagainya.
- Riwayat komit yang benar dalam Gita, dengan pesan yang mencerminkan esensi pesan, tanpa komitmen sementara.
Mempersiapkan Peninjauan
- Sebelum menerbitkan permintaan tarik, baca kode Anda 2-3 kali: dengan probabilitas tinggi, Anda sendiri akan menemukan kesalahan di sana, yang akan menghemat waktu untuk peninjau. Periksa bahwa tidak ada kesalahan yang dapat dideteksi secara otomatis - kesalahan gaya kode, tes yang dibatalkan. Pastikan bahwa kode tersebut tidak memiliki komentar sementara dan kode debug, dan juga periksa apakah kode Anda cocok dengan panduan gaya yang diterima.
- Jika Anda membuat permintaan tarikan dalam proses mengerjakan tugas, tulis “[WIP]” di pos dan beri tanda “work in progress”. Ketika pekerjaan selesai, hapus tag dan informasikan dalam komentar terpisah sehingga pihak yang berkepentingan tahu bahwa kode dapat dilihat.
- Bersiaplah untuk menunjukkan resensi mini demo pada tugas.
- Berikan sedikit kode untuk ditinjau. 200-300 baris perubahan - batas untuk ulasan yang efektif.
- Buat perubahan independen dalam komit terpisah.
- Jelaskan komitmen dengan pesan singkat dan informatif.
- Lakukan refactoring sebagai komit terpisah, lebih mudah untuk melihat perubahan dalam logika, esensi dari tugas.
- Memformat kode sebagai komit terpisah sebelum perubahan besar, atau bahkan sebagai permintaan tarikan terpisah.
- Jangan melakukan perubahan kecil. Misalnya, menambahkan jeda baris dalam file di mana Anda tidak mengubah apa pun.
- Dalam judul permintaan tarik, jelaskan secara singkat dan informatif esensi dari perubahan tersebut.
- Jelaskan masalah dan solusi dalam permintaan tarik. Jelaskan solusi alternatif dan mengapa solusi saat ini dipilih. Jika perubahan terkait dengan antarmuka, lampirkan tangkapan layar "sebelum" dan "setelah".
- Dalam permintaan tarik, berikan tautan ke tugas, dan di tugas itu tautan ke permintaan tarik.
- Terkadang berguna untuk mendiskusikan solusi yang dipilih dengan pengulas sebelum menulis kode. Ini akan membantu menemukan solusi terbaik untuk masalah dan menyederhanakan proses peninjauan.
Pilihan Peninjau
- Berikan tugas ulasan kepada spesialis di bidang yang relevan.
- Jika beberapa perintah berfungsi dengan beberapa kode, akan bermanfaat untuk memilih peninjau dari tim lain untuk menyebarkan pengetahuan.
- Petugas percobaan mungkin bukan peninjau yang bertanggung jawab, tetapi dapat berpartisipasi dalam proses peninjauan.
- Jangan berikan semua tugas Anda pada ulasan ke orang yang sama - minta ulasan dari orang yang berbeda.
- Jika masalahnya melibatkan sepotong kode non-sepele yang dipahami orang tertentu, perlihatkan perubahan padanya, terlepas dari siapa peninjau yang bertanggung jawab. Juga ingat bahwa setiap repositori memiliki pengelola, mereka tahu lebih banyak tentang kode ini dan mengawasi pengembangan.
- Sisa dari reviewer dipilih secara sewenang-wenang, dengan kesepakatan bersama dari para pihak. Gunakan rekomendasi pada github berdasarkan “kesalahan” kode yang terpengaruh untuk membantu Anda memilih.
- Setelah memilih resensi, tentukan itu sebagai Penerima dalam permintaan tarik. Daftar semua permintaan tarik yang ditetapkan untuk Anda.
Proses Peninjauan, Umum
Mengacu pada pembuat kode dan peninjau.
- Semua kode adalah umum, tidak ada konsep seperti "kode saya" atau "kode Anda". Ini berarti bahwa setiap pengembang bertanggung jawab atas setiap baris kode, dan bukan hanya orang yang menulis baris ini.
- Ciptakan suasana saling pengertian, bersikap sopan dan ramah, menghargai dan menghormati satu sama lain, jangan memaksakan pendapat Anda. Dengarkan pendapat lawan dan jangan berpegang teguh pada prinsip Anda. Jangan mengubah ulasan menjadi pengalaman negatif bagi kolega.
- Ajukan pertanyaan jika ada sesuatu yang tidak jelas. Berdebat dan tentukan pertanyaan dan jawaban. Mungkin tidak jelas bagi penulis kode apa yang dimaksud dengan pertanyaan "mengapa begitu?", Tetapi pengulas tidak memahami argumentasi dari jawaban "tidak setuju".
- Jangan meregangkan proses peninjauan, menghemat waktu, cepat menanggapi komentar, berdiskusi secara lisan, jangan memancing diskusi yang panjang dan jangan mengembangbiakkan "holivar". Jika Anda tidak dapat dengan cepat mencapai konsensus, cari bantuan dari kolega Anda, pengelola, atau manajer area fungsional.
- Jika tugas tidak pada beberapa baris, luangkan 10-15 menit dengan pengulas pada ulasan kode bersama, akan berguna untuk melakukan ini bahkan sebelum membuat permintaan tarik. Diskusikan esensi tugas dan solusi, lihat bagaimana itu terjadi dan menjadi dalam lingkungan kerja. Ini akan membantu pengulas untuk menyelami konteks tugas dengan lebih baik. Sebagian besar komentar akan tetap tidak tertulis, yang akan menghemat waktu semua orang.
- Setelah diskusi lisan, selalu uraikan keputusan yang diambil dan alasannya dalam permintaan tarik. Tanggung jawab untuk uraian terletak pada pembuat kode.
- Jika kode berisi jenis kesalahan yang sama, pengulas harus fokus pada perhatian pembuat kode dalam komentar pertama atau kedua tanpa mengomentari setiap entri, dan penulis harus menganalisis kode untuk jenis kesalahan yang sama sebelum menerbitkan koreksi.
- Puji atas keputusan sukses penulis dan saran peninjau.
- Tinggalkan komentar tentang perubahan dalam permintaan tarikan itu sendiri, dan bukan atas komitmen individu. Dengan demikian, semua korespondensi akan berada di satu tempat, termasuk setelah rebase.
- Tanggapi komentar di utas diskusi yang sama tempat mereka memulai. Jika komentar mengacu pada seluruh permintaan tarik atau beberapa komentar di utas yang sama, kutip komentar yang dikomentari. Untuk beralih dari email ke utas diskusi yang sudah ketinggalan zaman, alih-alih tautan “melihatnya di GitHub”, gunakan tautan “di jalur / ke / file”.
- Jika selama proses peninjauan keputusan kardinal dibuat dari sudut pandang standar pengkodean atau perjanjian formal lainnya, pembuat kode berkewajiban untuk menuliskan keputusan ini dalam dokumen yang relevan.
- Ulasan tidak hanya tentang kode, tetapi tentang seluruh tugas. Jangan memperlakukan persyaratan dalam tugas atau tata ruang sebagai kebenaran tertinggi - semua orang membuat kesalahan dan tidak ada yang bisa memperhitungkan semua nuansa. Tampilan yang segar dan saran yang masuk akal hanya akan menguntungkan produk.
Tinjau proses oleh penulis kode
- Tugas itu tidak selesai sampai lulus ulasan, pengujian dan rilis pada "prod."
- Tanggapi semua komentar pengulas, jangan tinggalkan komentar yang tidak dijawab, terlepas dari apakah Anda menerimanya atau tidak.
- Pikirkan tentang pertanyaan yang muncul atau mungkin muncul selama peninjauan. Mungkin bagian kode tidak ada komentar atau lebih baik menulis kode lebih eksplisit.
- Jangan perbaiki komit yang ada dengan komit gend - ubah, sebagai gantinya, buat perubahan sebagai komit terpisah, satu komit untuk setiap perbaikan. Memperbaiki komitmen yang ada sangat menyulitkan proses peninjauan, karena Anda harus melihat semua kode lagi.
- Setelah menambahkan komit baru ke permintaan tarik, tulis di komentar terpisah ringkasan perubahan sehingga pihak yang berkepentingan mengetahui. Ini berlaku untuk koreksi selama peninjauan, serta koreksi selama pengujian.
- Setelah ditinjau, sebelum mengirim tugas untuk pengujian, tulis ulang riwayat commit (git rebase --interactive), lakukan koreksi pada masing-masing commit dan hapus komit sementara. Periksa opsi --autosquash untuk menyederhanakan proses.
Proses Review oleh Reviewer
- Jika Anda sibuk pada saat permintaan peninjauan, beri tahu saya kapan Anda akan memulai peninjauan.
- Jangan menuntut, tetapi sarankan untuk melakukan perubahan.
- Komentari kode, bukan orang yang menulisnya.
- Anda bertanggung jawab atas kode tertulis, mendekati ulasan sesuai, tetapi ini tidak berarti bahwa pembuat kode harus benar-benar mematuhi semua persyaratan Anda. Ingat, banyak hal dapat dilakukan dengan cara yang berbeda.
- Ikuti tujuan ulasan dan sarankan pengeditan substantif. Jangan memaksakan perubahan yang tidak penting. Tunjukkan pentingnya koreksi dalam komentar.
- Jika Anda menemukan masalah serius, jeda ulasan dan tunggu penulis untuk memperbaikinya. Kemungkinan besar, setelah koreksi masih perlu direvisi lagi.
- Perhatikan tidak hanya apa yang telah diubah, tetapi juga apa yang belum diubah. Cari dan tunjukkan pada penulis kode yang seharusnya diubah, tetapi tidak (lupa impor atau kelas yang tidak digunakan, menggunakan kode refactored di tempat lain, dll.).
- Setelah melakukan perubahan oleh pembuat kode, tinjau koreksi dan tinjau kembali seluruh permintaan tarik. Mungkin, dengan koreksi, Anda akan memiliki komentar atau pertanyaan baru.
- Jangan buang waktu meninjau kode yang tidak berubah sebagai bagian dari tugas. Alokasi bagian kode ke fungsi dianggap sebagai perubahan. Transfer kode "sebagaimana adanya" tidak dianggap sebagai perubahan. Reformasi kode dalam file yang terpengaruh adalah atas kebijaksanaan penulis.
- Peninjau tidak mengedit kode secara independen di cabang, karena ia sangat menginginkannya atau lebih mudah. Perubahan dilakukan oleh pembuat kode.
- Jika Anda melakukan revisi, cobalah untuk tidak menunda atau beralih ke tugas lain yang merugikan arus
Bahan bekas dan tautan terkait
PS Bagikan aturan, rekomendasi, dan kasus pengguna yang bermanfaat tentang proses peninjauan dalam komentar