Dari dokumentasi Praktek Teknik Google

Panduan ini memberikan praktik terbaik untuk melakukan tinjauan kode berdasarkan pengalaman bertahun-tahun. Bersama-sama, mereka membuat satu dokumen, dibagi menjadi banyak bagian. Tidak perlu membaca semuanya, tetapi sering untuk diri sendiri dan tim Anda, lebih baik mempelajari panduan ini secara penuh.

• Standar Peninjauan Kode
  
• Apa yang harus diperiksa kode
  
• Ubah Daftar Navigasi (CL)
  
• Kecepatan ulasan kode
  
• Cara menulis komentar
  
• Cara mengatasi resistensi

Lihat juga Panduan Penulis CL untuk saran terperinci tentang pengembang yang komitnya ditinjau.

Standar Peninjauan Kode

Tujuan utama tinjauan kode adalah untuk menjamin peningkatan berkelanjutan basis kode Google. Semua alat dan proses didedikasikan untuk tujuan ini.

Sejumlah kompromi dibutuhkan di sini.

Pertama, pengembang harus mampu menyelesaikan masalah mereka dengan sukses. Jika Anda tidak pernah mengirim kode, maka basis kode tidak akan pernah membaik. Selain itu, jika peninjau sangat menyulitkan pekerjaan apa pun , maka di masa mendatang, pengembang tidak tertarik mengusulkan peningkatan.

Di sisi lain, itu adalah tanggung jawab peninjau untuk memastikan bahwa kualitas CL tidak mengurangi kualitas keseluruhan basis kode dari waktu ke waktu. Ini bisa sulit, karena sering kali degradasi terjadi karena sedikit penurunan kualitas kode dari waktu ke waktu, terutama jika tim berada di bawah tekanan parah dari tenggat waktu dan merasa bahwa ia memiliki hak untuk meningkatkan utang teknis.

Selain itu, peninjau bertanggung jawab atas kode yang ditinjau. Dia ingin memastikan bahwa basis kode tetap konsisten, didukung dan cocok dengan semua hal lain yang disebutkan di bagian "Apa yang harus diperiksa dalam kode" .

Dengan demikian, kami mendapatkan aturan berikut sebagai standar untuk tinjauan kode:

Biasanya, pengulas harus mendukung CL segera setelah mencapai keadaan di mana ia pasti meningkatkan kualitas keseluruhan dari kode sistem, bahkan jika CL tidak sempurna.

Ini adalah tinjauan kode utama di antara semua prinsip.

Tentu saja, ia memiliki keterbatasan. Misalnya, jika CL menambahkan fungsi yang tidak ingin dilihat oleh reviewer di dalam sistem, maka reviewer pasti dapat menolak untuk melakukan, bahkan jika kodenya berkualitas baik.

Poin kuncinya di sini adalah tidak ada kode "sempurna" - hanya ada kode yang lebih baik . Peninjau seharusnya tidak mengharuskan penulis untuk memoles setiap fragmen kecil. Sebaliknya, peninjau harus menyeimbangkan kebutuhan untuk kemajuan lebih lanjut atas pentingnya perubahan yang diusulkan. Alih-alih berjuang untuk yang ideal, pengulas harus berusaha untuk perbaikan terus - menerus . Komit, yang umumnya meningkatkan kemampuan pemeliharaan, keterbacaan, dan kelengkapan sistem, tidak dapat ditunda selama berhari-hari atau berminggu-minggu karena itu tidak "sempurna."

Peninjau selalu dapat meninggalkan komentar tentang peningkatan kode, tetapi perubahan yang tidak terlalu penting harus ditandai, misalnya, dengan awalan Nit: sehingga penulis tahu bahwa ini hanyalah sudut pandang yang dapat ia abaikan.

Catatan Tidak ada dalam dokumen ini yang membenarkan CL yang pasti menurunkan kualitas keseluruhan dari kode sistem. Ini hanya mungkin dalam keadaan darurat .

Pendampingan

Tinjauan kode juga dapat menjadi penting untuk mengajarkan pengembang sesuatu yang baru tentang bahasa, struktur, atau prinsip umum desain perangkat lunak. Selalu menyenangkan untuk meninggalkan komentar yang membantu pengembang mempelajari sesuatu yang baru. Berbagi pengetahuan berkontribusi untuk meningkatkan kode sistem dari waktu ke waktu. Hanya perlu diingat bahwa jika Anda meninggalkan komentar murni pendidikan yang tidak penting untuk memenuhi standar yang dijelaskan di sini, tambahkan awalan Nit untuk itu : atau menunjukkan bahwa penulis tidak diharuskan untuk mengizinkannya.

Prinsip

• Fakta dan data teknis lebih penting daripada pendapat dan preferensi pribadi.
  
• Dalam hal gaya, otoritas absolut adalah panduan untuk gaya . Detail gaya apa pun (ruang, dll.) Murni yang tidak termasuk dalam panduan gaya adalah masalah preferensi pribadi. Gaya harus cocok dengan apa adanya. Jika tidak ada gaya sebelumnya, terima penulis.
  
• Aspek desain perangkat lunak hampir tidak pernah masalah gaya murni atau preferensi pribadi. Mereka didasarkan pada prinsip-prinsip dasar dan harus ditentukan oleh prinsip-prinsip ini, dan bukan hanya pendapat pribadi. Terkadang ada beberapa opsi yang valid. Jika penulis dapat menunjukkan (baik menggunakan data atau berdasarkan prinsip-prinsip teknik padat) bahwa pendekatan tertentu sama efektifnya, pengulas harus menerima preferensi penulis. Kalau tidak, pilihannya ditentukan oleh prinsip pengembangan standar.
  
• Jika tidak ada aturan lain yang berlaku, maka pengulas dapat meminta penulis untuk mengamati keseragaman dengan basis kode saat ini, jika ini tidak memperburuk kondisi umum sistem.

Resolusi Konflik

Dalam konflik apa pun, langkah pertama harus selalu menjadi keinginan pengembang dan peninjau untuk mencapai konsensus berdasarkan isi dokumen ini dan dokumen lain dalam Panduan Penulis CL dan Panduan Reviewer ini.

Ketika sangat sulit untuk mencapai konsensus, pertemuan pribadi atau konferensi video antara pengulas dan penulis dapat membantu (jika Anda melakukannya, pastikan untuk menuliskan hasil diskusi dalam komentar pada komit untuk pembaca masa depan).

Jika ini tidak menyelesaikan situasi, maka cara yang paling umum adalah eskalasi. Seringkali itu terdiri dari diskusi yang lebih luas dengan tim, menarik pemimpin tim, menghubungi pengelola atau manajer pengembangan. Jangan biarkan komit berlama-lama karena fakta bahwa penulis dan reviewer tidak dapat mencapai kesepakatan.

Apa yang harus diperiksa kode

Catatan Saat mempertimbangkan masing-masing item ini, pastikan untuk mempertimbangkan Tinjauan Kode Standar .

Desain

Yang paling penting adalah mempertimbangkan keseluruhan proyek (desain) dalam ulasan kode. Apakah interaksi antara berbagai bagian kode masuk akal? Apakah perubahan ini berlaku untuk basis kode atau pustaka Anda? Apakah CL terintegrasi dengan baik dengan seluruh sistem? Apakah sekarang saatnya menambahkan fungsi ini?

Fungsionalitas

Apakah CL ini melakukan apa yang dimaksudkan pengembang? Apakah ini baik untuk pengguna kode ini? Yang dimaksud dengan "pengguna" adalah pengguna akhir (jika mereka dipengaruhi oleh perubahan) dan pengembang (yang harus "menggunakan" kode ini di masa mendatang).

Pada dasarnya, kami berharap bahwa bahkan sebelum melakukan, pengembang akan menguji kode mereka dengan cukup baik agar dapat berfungsi dengan benar. Tetapi sebagai peninjau, Anda masih perlu memikirkan kasus-kasus ekstrem, mencari masalah konkurensi, mencoba berpikir sebagai pengguna, dan bahkan menonton sambil membaca kode bahwa tidak ada kesalahan yang jelas.

Jika mau, Anda dapat memeriksa kinerjanya. Ini paling penting jika kode memengaruhi pengguna, seperti mengubah UI . Sulit untuk memahami bagaimana beberapa perubahan akan mempengaruhi pengguna ketika Anda baru saja membaca kode. Untuk perubahan seperti itu, Anda dapat meminta pengembang untuk memberikan demo jika terlalu sulit bagi Anda untuk mempelajari kode dan mencobanya sendiri.

Poin lain ketika sangat penting untuk memikirkan fungsionalitas selama tinjauan kode adalah jika beberapa jenis pemrograman paralel terjadi di CL, yang secara teoritis dapat menyebabkan kebuntuan atau kondisi balapan. Masalah seperti itu sangat sulit dideteksi dengan hanya menjalankan kode; biasanya perlu bahwa seseorang (baik pengembang dan peninjau) dengan hati-hati memikirkan mereka dan memastikan bahwa tidak ada masalah yang diperkenalkan (perhatikan bahwa ini juga merupakan alasan yang baik untuk tidak menggunakan model paralelisme di mana kondisi balapan atau kebuntuan dimungkinkan - ini dapat dilakukan dengan kode sangat sulit dimengerti atau kode ditinjau).

Kesulitan

Apakah CL lebih rumit dari yang seharusnya? Periksa di setiap level: baris terpisah, fungsi, kelas. "Kompleksitas berlebihan" biasanya berarti ketidakmampuan untuk dengan cepat memahami saat membaca . Ini juga dapat berarti bahwa pengembang lebih mungkin untuk memperkenalkan kesalahan ketika mencoba menelepon atau memodifikasi kode ini .

Jenis kompleksitas khusus adalah rekayasa berlebihan, ketika pengembang telah membuat kode lebih universal daripada yang seharusnya, atau menambahkan fungsionalitas yang saat ini tidak dibutuhkan oleh sistem. Peninjau harus sangat waspada tentang rekayasa berlebihan. Dorong pengembang untuk memecahkan masalah yang pasti harus diselesaikan sekarang, daripada masalah yang mungkin perlu diselesaikan di masa depan. Masalah di masa depan harus dipecahkan ketika muncul, dan Anda dapat melihat bentuk dan persyaratan aktualnya di Alam semesta fisik.

Tes

Meminta unit, integrasi, atau tes ujung ke ujung yang relevan dengan perubahan tersebut. Secara umum, tes harus ditambahkan ke CL yang sama dengan kode produksi jika CL tidak menangani keadaan darurat .

Pastikan tesnya benar, masuk akal, dan bermanfaat. Tes tidak menguji diri mereka sendiri, dan kami jarang menulis tes untuk tes kami - seseorang harus memastikan bahwa tes itu valid.

Apakah tes benar-benar gagal pada kode yang rusak? Jika kode berubah, apakah akan ada false positive? Apakah setiap tes membuat pernyataan yang sederhana dan bermanfaat? Apakah tes dibagi dengan benar antara metode tes yang berbeda?

Ingatlah bahwa tes adalah kode yang juga harus didukung. Jangan biarkan kerumitan di dalamnya hanya karena itu bukan bagian dari file biner utama.

Penamaan

Sudahkah pengembang memilih nama baik di mana-mana? Nama yang baik cukup panjang untuk sepenuhnya menyampaikan apa elemen itu atau apa fungsinya, tanpa terlalu lama sehingga menjadi sulit dibaca.

Komentar

Apakah pengembang menulis komentar yang jelas dalam bahasa sederhana? Apakah semua komentar perlu? Komentar biasanya berguna ketika mereka menjelaskan mengapa beberapa kode ada, dan seharusnya tidak menjelaskan apa yang dilakukan kode ini. Jika kode tidak cukup jelas untuk menjelaskan sendiri, maka harus disederhanakan. Ada beberapa pengecualian (misalnya, komentar yang menjelaskan tindakan kode sering sangat berguna untuk ekspresi reguler dan algoritme yang kompleks), tetapi sebagian besar komentar dimaksudkan untuk informasi yang tidak dapat berisi kode itu sendiri, misalnya, mendukung keputusan.

Mungkin juga berguna untuk melihat komentar dalam kode sebelumnya. Mungkin ada TODO, yang sekarang dapat dihapus, atau komentar yang tidak merekomendasikan perubahan ini, dll.

Perhatikan bahwa komentar berbeda dari dokumentasi untuk kelas, modul, atau fungsi, yang menjelaskan tugas kode, bagaimana kode itu harus digunakan, dan bagaimana perilakunya.

Gaya

Kami memiliki panduan gaya Google untuk semua bahasa utama, dan bahkan sebagian besar bahasa minor. Pastikan CL tidak bertentangan dengan panduan gaya yang relevan.

Jika Anda ingin meningkatkan beberapa elemen yang tidak ada dalam panduan gaya, tambahkan catatan ke komentar ( Nit :) . Pengembang akan tahu bahwa ini adalah komentar pribadi Anda, yang tidak mengikat. Jangan memblokir pengiriman komitmen hanya berdasarkan preferensi pribadi Anda.

Penulis tidak boleh menggabungkan perubahan gaya yang signifikan dengan perubahan lainnya. Ini membuatnya sulit untuk melihat perubahan dalam CL, menyulitkan penggabungan, kembalikan kode, dan menyebabkan masalah lain. Misalnya, jika penulis ingin memformat ulang seluruh file, minta perubahan gaya dalam satu CL, lalu kirim CL dengan perubahan fungsional.

Dokumentasi

Jika output CL mengubah sesuatu dalam perakitan, pengujian, prosedur interaksi, atau rilis kode, periksa pembaruan untuk dokumentasi yang relevan, termasuk file README, halaman g3doc, dan semua dokumen referensi yang dihasilkan. Jika CL menghapus kode atau membuatnya usang, pertimbangkan apakah akan juga menghapus dokumentasi. Jika dokumentasi tidak ada, minta dibuat.

Setiap baris

Lihat setiap baris dalam kode. Meskipun setiap file data, kode yang dihasilkan, atau struktur data besar dapat ditinjau secara singkat, tetapi dengan hati-hati membaca setiap kelas, fungsi, atau blok kode yang ditulis oleh seseorang, tidak pernah berasumsi secara default bahwa semuanya beres. Jelas, beberapa kode pantas dipelajari lebih teliti daripada yang lain - Anda memutuskan sendiri, tetapi Anda setidaknya harus yakin bahwa Anda memahami operasi seluruh kode.

Jika terlalu sulit bagi Anda untuk membaca kode dan ini memperlambat ulasan, Anda harus memberi tahu pengembang dan menunggu sampai ia memberikan kejelasan sebelum melanjutkan. Di Google, kami mempekerjakan insinyur perangkat lunak yang hebat, dan Anda adalah salah satunya. Jika Anda tidak dapat memahami kode tersebut, sangat mungkin pengembang lain tidak akan dapat melakukannya. Dengan cara ini, Anda juga membantu pengembang di masa depan memahami kode ini saat meminta kejelasan pengembang.

Jika kodenya dapat dimengerti, tetapi Anda tidak merasa cukup memenuhi syarat untuk mengevaluasi suatu fragmen tertentu, pastikan bahwa ada pengulas di CL yang memenuhi syarat, terutama untuk masalah kompleks seperti keamanan, konkurensi, aksesibilitas, internasionalisasi, dll.

Konteks

Seringkali berguna untuk melihat CL dalam konteks yang luas. Biasanya, alat peninjau kode hanya menunjukkan beberapa baris di dekat tempat perubahan. Terkadang Anda perlu melihat seluruh file untuk memastikan bahwa perubahan benar-benar masuk akal. Misalnya, Anda melihat penambahan hanya empat baris, tetapi jika Anda melihat keseluruhan file, maka keempat baris ini menggunakan metode 50-baris, yang sekarang benar-benar harus dipecah menjadi yang lebih kecil.

Juga bermanfaat untuk memikirkan CL dalam konteks sistem secara keseluruhan. Apakah ini meningkatkan kualitas kode sistem atau membuatnya lebih kompleks, kurang teruji, dll.? Jangan terima komitmen yang menurunkan kode sistem. Sebagian besar sistem menjadi rumit dengan banyaknya perubahan kecil, jadi penting untuk mencegah bahkan kesulitan kecil di sana.

Bagus

Jika Anda melihat sesuatu yang baik dalam komit, beri tahu pengembang, terutama ketika dia telah memecahkan masalah yang dijelaskan dalam salah satu komentar Anda dengan cara terbaik. Ulasan kode seringkali hanya berfokus pada bug, tetapi mereka juga harus mendorong dan menghargai praktik yang baik. Dari sudut pandang mentoring, kadang-kadang bahkan lebih penting untuk memberi tahu pengembang apa yang dia lakukan dengan benar, dan bukan di mana dia melakukan kesalahan.

Ringkasan

Saat menjalankan tinjauan kode, pastikan bahwa:

• Kode ini dirancang dengan baik.
  
• Fungsionalitas baik untuk pengguna kode.
  
• Setiap perubahan pada UI adalah wajar dan terlihat bagus.
  
• Setiap pemrograman bersamaan aman.
  
• Kode tidak lebih rumit dari yang seharusnya.
  
• Pengembang tidak mengimplementasikan apa yang mungkin dibutuhkan di masa depan dengan prospek yang tidak diketahui.
  
• Kode dipagari dengan unit test yang sesuai.
  
• Tes dirancang dengan baik.
  
• Pengembang menggunakan nama yang jelas di mana-mana.
  
• Komentar dapat dimengerti dan bermanfaat, dan pada dasarnya menjawab pertanyaan mengapa? tapi tidak apa?
  
• Kode ini didokumentasikan dengan baik (biasanya di g3doc).
  
• Kode ini sesuai dengan panduan gaya kami.

Selama ulasan, pastikan untuk melihat setiap baris kode, lihat konteksnya , pastikan Anda meningkatkan kualitas kode dan memuji pengembang untuk kebaikan yang berhasil mereka lakukan.

Navigasi CL dalam ulasan kode

Ringkasan

Sekarang Anda tahu apa yang harus diperiksa dalam kode , apa cara paling efisien untuk melakukan tinjauan kode pada banyak file?

1. Apakah perubahan ini masuk akal? Apakah dia punya deskripsi yang bagus?
   
2. Pertama lihat bagian terpenting. Apakah dirancang dengan baik?
   
3. Lihatlah sisa CL dalam urutan yang sesuai.

Langkah pertama: lihat seluruh komit

Lihatlah deskripsi CL dan apa fungsinya secara umum. Apakah perubahan ini masuk akal? Jika seharusnya tidak ditulis pada awalnya, harap segera menanggapi dengan penjelasan mengapa itu tidak diperlukan. Saat Anda menolak perubahan seperti itu, sebaiknya tawarkan pengembang apa yang harus dilakukan.

Misalnya, Anda mungkin berkata, "Sepertinya Anda melakukan pekerjaan dengan baik, terima kasih!" Namun, kami sebenarnya akan menghapus sistem FooWidget, jadi kami tidak ingin melakukan perubahan baru sekarang. Bagaimana kalau Anda refactoring kelas BarWidget baru saja? ”

Harap dicatat bahwa peninjau tidak hanya menolak CL saat ini dan memberikan saran alternatif, tetapi juga melakukannya dengan sopan . Sopan santun seperti itu penting karena kami ingin menunjukkan bahwa kami saling menghormati sebagai pengembang, bahkan ketika kami tidak setuju satu sama lain.

Jika Anda mendapatkan beberapa CL yang tidak diinginkan, Anda harus meninjau proses pengembangan di tim Anda atau aturan yang diterbitkan untuk kontributor eksternal untuk meningkatkan komunikasi saat menulis CL. Lebih baik memberi tahu orang-orang “tidak” sebelum mereka melakukan banyak pekerjaan yang harus dibuang atau ditulis ulang dengan berat.

Langkah Dua: Pelajari Bagian Dasar CL

Temukan file atau file yang mewakili bagian "utama" dari CL ini. Seringkali ada satu file dengan perubahan paling logis, dan ini adalah bagian utama dari CL. Pertama lihat bagian-bagian utama ini. Ini membantu untuk memahami konteks bagian yang lebih kecil dari CL, dan umumnya mempercepat eksekusi tinjauan kode. Jika CL terlalu besar, tanyakan pengembang apa yang harus dilihat terlebih dahulu, atau minta dia untuk membagi CL menjadi beberapa bagian .

Jika Anda melihat masalah serius di bagian utama CL, Anda harus segera mengirim komentar ini, bahkan jika Anda tidak punya waktu untuk melihat sisa CL sekarang. Bahkan, melihat sisa kode mungkin hanya buang-buang waktu, karena jika masalahnya cukup signifikan, banyak potongan kode lain yang dimaksud akan hilang dan tidak masalah.

Ada dua alasan utama mengapa sangat penting untuk segera mengirim komentar utama ini:

• Pengembang sering mengirim CL, dan kemudian segera memulai pekerjaan baru berdasarkan itu, sambil menunggu hasil tinjauan kode. Jika CL memiliki masalah serius, mereka harus mengerjakan ulang CL berikutnya. Dianjurkan untuk mengidentifikasi kesalahan sedini mungkin sebelum mereka melakukan banyak pekerjaan tambahan di atas desain yang bermasalah.
  
• Perubahan besar membutuhkan waktu lebih lama daripada suntingan kecil. Hampir semua pengembang memiliki tenggat waktu. Agar tetap di dalamnya dan tidak mengurangi kualitas kode, refactoring besar apa pun harus dimulai sesegera mungkin.

Langkah Tiga: Gulir melalui sisa CL dalam urutan yang sesuai.

Setelah memastikan bahwa tidak ada masalah serius dengan desain CL secara keseluruhan, cobalah mencari tahu urutan logis untuk melihat file dan pastikan tidak ada yang terlewatkan. Biasanya, ketika Anda melihat file-file utama, cara termudah adalah dengan cukup menelusuri sisanya dalam urutan di mana alat peninjau kode menyajikannya. Kadang-kadang juga bermanfaat untuk membaca tes pertama, dan kemudian kode utama, karena Anda akan memiliki gagasan tentang apa arti dari perubahan itu.

Kecepatan ulasan kode

Mengapa peninjauan kode harus dilakukan dengan cepat?

Di Google, kami mengoptimalkan kecepatan kolaborasi , bukan kecepatan pengembang individu. Kecepatan kerja individu itu penting, hanya saja tidak begitu prioritas dibandingkan dengan kecepatan kerja tim.

Ketika Anda perlahan melihat kode, beberapa hal terjadi:

• Kecepatan tim secara keseluruhan menurun. Ya, jika seseorang tidak cepat menanggapi ulasan kode, dia melakukan pekerjaan lain. Namun, untuk anggota tim lainnya, fitur-fitur baru dan perbaikan bug ditunda berdasarkan hari, minggu, atau bulan, karena masing-masing CL menunggu ulasan kode dan ulasan kode berulang.
  
• -. , , . , «» . (, ), , . - .
  
• Kualitas kode mungkin menurun. Memperlambat tinjauan kode meningkatkan risiko bahwa pengembang tidak akan mengirim CL yang sebaik mungkin. Ulasan lambat juga menghambat pembersihan kode, refactoring, dan perbaikan lebih lanjut untuk CL yang ada.

Bagaimana cara menjalankan review kode dengan cepat?

Jika Anda tidak berada di tengah-tengah tugas yang terfokus, Anda harus membuat kode ulasan segera setelah itu tiba.

Satu hari kerja adalah waktu maksimum untuk jawaban (yaitu, ini adalah hal pertama keesokan paginya).

Mengikuti pedoman ini berarti bahwa CL umumnya harus menerima beberapa putaran tinjauan (jika perlu) dalam satu hari.

Kecepatan dan gangguan

Ada satu saat ketika prioritas kecepatan pribadi melebihi kecepatan tim. Jika Anda berada di tengah-tengah tugas yang terfokus, seperti menulis kode, jangan terganggu oleh ulasan kode. Penelitian telah menunjukkan bahwa pengembang perlu waktu lama untuk kembali ke aliran pengembangan yang lancar setelah gangguan. Dengan demikian, gangguan dari pengkodean sebenarnya biaya tim lebih dari meminta pengembang lain untuk menunggu sedikit untuk meninjau kode.

Sebaliknya, tunggu breakpoint dalam pekerjaan Anda. Misalnya, setelah menyelesaikan tugas saat ini, setelah makan siang, kembali dari rapat, kembali dari dapur kecil kantor, dll.

Balasan cepat

Ketika kita berbicara tentang kecepatan tinjauan kode, kita tertarik pada waktu respons , dan bukan berapa banyak waktu yang diperlukan untuk seluruh proses sampai akhir. Idealnya, keseluruhan proses juga harus cepat, tetapi bahkan lebih penting bahwa jawaban individu cepat tiba daripada seluruh proses .

Bahkan jika seluruh proses peninjauan kode memakan waktu, ketersediaan tanggapan cepat dari peninjau sepanjang proses sangat menyederhanakan kehidupan pengembang yang mungkin terganggu oleh respons "lambat".

Jika Anda terlalu sibuk untuk ulasan lengkap segera setelah menerima permintaan, Anda masih dapat dengan cepat menanggapi dengan pesan tentang tenggat waktu atau menawarkan ulasan kepada pengulas lain yang dapat merespons lebih cepat, atauberikan beberapa komentar umum awal (catatan: semua ini tidak berarti bahwa Anda harus menghentikan pengkodean bahkan untuk mengirim respons seperti itu - kirim respons pada breakpoint yang wajar dalam pekerjaan Anda).

Adalah penting bahwa pengulas menghabiskan cukup waktu meninjau dan memastikan bahwa "LGTM" mereka berarti "kode ini sesuai dengan standar kami ". Namun, jawaban individu idealnya harus cepat pula .

Ulasan kode antara zona waktu

Ketika bekerja di antara zona waktu yang berbeda, cobalah untuk menjawab penulis ketika dia masih di kantor. Jika dia sudah pulang, pastikan untuk mencoba mengirim jawaban sebelum dia kembali ke kantor pada hari berikutnya.

LGTM khusus

Untuk alasan kecepatan, ada situasi tertentu di mana peninjau harus memberikan LGTM / persetujuan, bahkan dalam kasus komentar yang tidak dijawab tentang CL. Ini dilakukan jika:

• Peninjau yakin bahwa pengembang akan mempertimbangkan semua komentar yang tersisa dengan benar.
  
• Perubahan lainnya kecil dan opsional .

Peninjau harus menunjukkan opsi mana yang ia maksudkan jika ini tidak jelas.

LGTM yang dicadangkan sangat berguna ketika pengembang dan peninjau berada di zona waktu yang berbeda, jika tidak, pengembang akan menunggu sepanjang hari untuk mendapatkan "Disetujui LGTM."

CL besar

Jika seseorang mengirimi Anda kode ulasan yang sangat besar sehingga Anda tidak yakin kapan bisa melihatnya, maka jawaban umumnya adalah meminta pengembang untuk membagi CL menjadi beberapa CL yang lebih kecil . Ini biasanya mungkin dan sangat berguna untuk pengulas, bahkan jika itu membutuhkan pekerjaan tambahan dari pengembang.

Jika CL tidak dapat dipecah menjadi CL yang lebih kecil dan Anda tidak punya waktu untuk dengan cepat melihat semua ini, setidaknya tuliskan beberapa komentar pada keseluruhan desain CL dan kirim kembali ke pengembang untuk perbaikan. Salah satu tujuan Anda sebagai peninjau harus selalu "membuka" pengembang atau mengizinkannya mengambil tindakan lebih lanjut tanpa mengorbankan kualitas kode.

Perbaikan ulasan kode dari waktu ke waktu

Jika Anda mengikuti rekomendasi ini dan secara ketat mendekati tinjauan kode, Anda akan menemukan bahwa seluruh proses dipercepat dan dipercepat dari waktu ke waktu. Pengembang akan mencari tahu apa yang diperlukan untuk kode berkualitas tinggi dan mengirimi Anda CL yang hebat sejak awal, sehingga semakin sedikit waktu untuk melihatnya. Peninjau belajar merespons dengan cepat dan tidak menambahkan penundaan yang tidak perlu ke proses peninjauan. Tetapi jangan kompromikan standar atau kualitas tinjauan kode untuk peningkatan kecepatan imajiner - pada kenyataannya, Anda tidak akan mencapai akselerasi keseluruhan dalam jangka panjang.

Situasi darurat

Ada juga situasi darurat ketika CL harus melalui seluruh proses tinjauan kode dengan sangat cepat, dan di mana prinsip-prinsip kualitas harus dilunakkan. Tapi tolong baca deskripsi situasi mana yang memenuhi syarat sebagai darurat dan yang tidak.

Cara menulis komentar dalam ulasan kode

Ringkasan

• Bersikap sopan.
  
• Jelaskan alasanmu.
  
• Hindari pesanan eksplisit dengan hanya menunjukkan masalah dan membiarkan pengembang memutuskan.
  
• Dorong pengembang untuk menyederhanakan kode atau menambahkan komentar alih-alih penjelasan sederhana untuk kompleksitas.

Kesopanan

Secara umum, penting untuk bersikap sopan dan hormat, dan juga sangat jelas dan bermanfaat bagi pengembang yang kode yang Anda lihat. Salah satu cara untuk melakukan ini adalah memastikan bahwa Anda selalu membuat komentar tentang kode dan tidak pernah tentang pengembang . Anda tidak harus selalu mengikuti praktik ini, tetapi Anda harus menggunakannya saat mengatakan sesuatu yang tidak menyenangkan atau kontroversial. Sebagai contoh:

Buruk: "Mengapa Anda menggunakan stream di sini jika jelas bahwa konkurensi tidak bermanfaat?"

Bagus: “Model concurrency di sini menambah kompleksitas pada sistem, dan saya tidak melihat manfaat kinerja aktual. Karena tidak ada keuntungan kinerja, yang terbaik untuk kode ini adalah utas tunggal daripada menggunakan beberapa utas. "

Jelaskan alasannya

Dalam contoh "baik" di atas, Anda dapat melihat bahwa itu membantu pengembang memahami mengapa Anda membuat komentar Anda. Anda tidak selalu perlu memasukkan informasi ini dalam komentar Anda, tetapi kadang-kadang pantas untuk memberikan sedikit penjelasan tentang logika Anda, praktik terbaik yang Anda ikuti, atau bagaimana saran Anda meningkatkan kualitas kode.

Petunjuk arah

Secara umum, membuat koreksi adalah tugas pengembang, bukan peninjau. Anda tidak diharuskan mengembangkan solusi konsep terperinci atau menulis kode untuk pengembang.

Namun, ini tidak berarti bahwa peninjau tidak dapat membantu di sini. Secara umum, keseimbangan yang tepat harus dicapai antara mengidentifikasi masalah dan memberikan bantuan langsung. Menunjukkan masalah dan memberi pengembang kesempatan untuk membuat keputusan sering membantu pengembang untuk belajar dan membuat peninjauan kode lebih mudah. Ini juga dapat mengarah ke solusi yang lebih baik, karena pengembang lebih dekat dengan kode daripada pengulas.

Namun, instruksi langsung, saran, atau bahkan kode terkadang lebih berguna. Tujuan utama dari tinjauan kode adalah untuk mendapatkan CL terbaik. Tujuan kedua adalah untuk meningkatkan keterampilan pengembang sehingga peninjauan membutuhkan waktu yang semakin sedikit bagi mereka.

Terima penjelasannya

Jika Anda meminta pengembang untuk menjelaskan sepotong kode yang tidak dapat dipahami, biasanya ini akan mengarah pada fakta bahwa ia akan menulis ulang dengan lebih jelas . Terkadang menambahkan komentar juga merupakan jawaban yang tepat, jika bukan hanya penjelasan kode yang terlalu rumit.

Penjelasan yang hanya ditulis di alat ulasan tidak akan membantu pembaca di masa depan. Mereka hanya dapat diterima dalam beberapa kasus, misalnya, ketika Anda melihat area yang Anda tidak terlalu kenal, dan pengembang menjelaskan apa yang seharusnya sudah diketahui oleh pembaca kode.

Cara mengatasi hambatan dalam proses peninjauan kode

Terkadang pengembang berdebat dalam proses peninjauan kode. Entah dia tidak setuju dengan proposal Anda, atau mengeluh bahwa Anda terlalu ketat pada umumnya.

Siapa yang benar

Ketika pengembang tidak setuju dengan proposal Anda, pertama-tama luangkan waktu untuk mempertimbangkan posisinya. Seringkali lebih dekat ke kode Anda dan karena itu mungkin benar-benar memiliki ide yang lebih baik dari beberapa aspek. Apakah masuk akal dalam argumennya? Apakah masuk akal dalam hal kualitas kode? Jika demikian, maka akui bahwa dia benar, dan pertanyaannya akan hilang.

Namun, pengembang tidak selalu benar. Dalam hal ini, peninjau harus menjelaskan lebih lanjut mengapa ia percaya bahwa usulannya benar. Penjelasan yang baik menunjukkan pemahaman tentang respons pengembang dan informasi tambahan tentang mengapa perubahan diperlukan.

Secara khusus, ketika peninjau menganggap bahwa usulannya akan meningkatkan kualitas kode, ia harus bersikeras jika ia menganggap bahwa peningkatan kualitas yang dihasilkan membenarkan pekerjaan tambahan. Meningkatkan kualitas kode, sebagai suatu peraturan, terjadi dalam langkah-langkah kecil.

Terkadang dibutuhkan beberapa putaran penjelasan sebelum benar-benar diterima. Pastikan Anda selalu tetap sopan , dan biarkan pengembang tahu bahwa Anda mendengarnya, tapi jangan setuju.

Tentang kebencian pengembang

Peninjau terkadang merasa bahwa pengembang kesal jika peninjau bersikeras untuk melakukan perbaikan. Terkadang pengembang benar-benar kesal, tetapi biasanya tidak lama, dan kemudian mereka akan sangat berterima kasih bahwa Anda membantu mereka meningkatkan kualitas kode mereka. Biasanya, jika Anda sopan dalam komentar Anda, para pengembang tidak benar-benar kesal sama sekali, dan kekhawatiran hanya ada di kepala reviewer. Biasanya gaya menulis komentar lebih membuat frustrasi daripada kegigihan pengulas mengenai kualitas kode.

Suntingan yang tertunda

Sumber khas kontroversi adalah bahwa pengembang (untuk alasan yang jelas) ingin menyelesaikan pekerjaan. Mereka tidak ingin melalui putaran lain ulasan untuk CL ini. Oleh karena itu, mereka mengatakan bahwa mereka akan menghapus sesuatu di CL nanti, dan sekarang Anda harus membuat LGTM untuk CL ini . Beberapa pengembang melakukan ini dengan sangat baik, dan segera menulis CL lain yang akan memperbaiki masalah. Namun, pengalaman menunjukkan bahwa semakin banyak waktu berlalu setelah CL asli, semakin kecil kemungkinan pengeditan ini terjadi. Bahkan, biasanya jika pengembang tidak segera melakukan pengeditanyang biasanya tidak pernah terjadi. Bukan karena pengembang tidak bertanggung jawab, tetapi karena mereka memiliki banyak pekerjaan, dan pengeditan hilang atau terlupakan di bawah jalan pekerjaan lain. Dengan demikian, biasanya yang terbaik adalah menuntut perbaikan segera sebelum komit masuk ke basis kode dan "selesai". Izinkan pengeditan yang tertunda adalah cara khas untuk merosot basis kode.

Jika CL memperkenalkan kompleksitas baru, maka itu harus diperbaiki sebelum mengirim, jika ini bukan keadaan darurat. Jika CL menunjukkan masalah lain yang tidak dapat diselesaikan saat ini, pengembang harus mendaftarkan bug di pelacak dan menugaskannya untuk dirinya sendiri agar ia tidak tersesat. Dia secara opsional dapat menulis komentar TODO dalam kode mengenai kesalahan ini.

Keluhan umum keparahan

Jika Anda terbiasa melakukan tinjauan kode yang agak dangkal, dan beralih ke mode ketat, beberapa pengembang akan mulai mengeluh dengan sangat keras. Peningkatan kecepatan tinjauan kode biasanya menyelesaikan keluhan ini.

Terkadang butuh waktu berbulan-bulan untuk menghilangkan keluhan, tetapi pada akhirnya, pengembang cenderung melihat nilai ulasan kode yang ketat karena mereka melihat betapa hebatnya kode tersebut. Terkadang pengunjuk rasa paling keras bahkan menjadi pendukung terkuat Anda ketika sesuatu terjadi yang membuat mereka benar-benar melihat nilai ulasan yang ketat.

Resolusi Konflik

Jika Anda melakukan semua hal di atas, tetapi masih mengalami konflik, lihat bagian Standar Peninjauan Kode untuk rekomendasi dan prinsip yang dapat membantu menyelesaikan konflik.