Apakah ulasan kode yang hanya menggunakan komentar kode adalah ide yang bagus?

Prasyarat

• Tim menggunakan DVCS
• IDE mendukung parsing komentar (seperti TODO dan lain-lain)
• Alat seperti CodeCollaborator mahal untuk anggaran
• Alat seperti gerrit terlalu rumit untuk dipasang atau tidak dapat digunakan

Alur kerja

• Penulis menerbitkan suatu tempat di cabang fitur repo pusat
• Reviewer mengambilnya dan memulai review

• Dalam hal beberapa pengulas pertanyaan / masalah buat komentar dengan label khusus, seperti "REV". Label semacam itu HARUS tidak dalam kode produksi - hanya pada tahap peninjauan:

  $somevar = 123;
  // REV Why do echo this here?
  echo $somevar;
  

• Ketika pengulas selesai mengirim komentar - itu hanya dilakukan dengan pesan "komentar" bodoh dan mendorong kembali

• Penulis menarik cabang fitur kembali dan menjawab komentar dengan cara yang sama atau meningkatkan kode dan mendorongnya kembali
• Ketika komentar "REV" habis, kita bisa berpikir, ulasan itu telah berhasil diselesaikan.
• Penulis mengubah cabang fitur secara interaktif, menekannya untuk menghapus komitmen "komentar" tersebut dan sekarang siap untuk menggabungkan fitur untuk mengembangkan atau membuat tindakan apa pun yang biasanya dilakukan setelah tinjauan internal yang berhasil

Dukungan IDE

Saya tahu, bahwa tag komentar khusus dimungkinkan di gerhana & netbeans. Tentu itu juga harus dalam keluarga blablaStorm.

Pertanyaan

1. Apakah menurut Anda metodologi ini layak?
2. Apakah Anda tahu sesuatu yang serupa?
3. Apa yang bisa diperbaiki di dalamnya?

Idenya sebenarnya sangat bagus. Berlawanan dengan alur kerja umum, Anda menyimpan ulasan secara langsung dalam kode, jadi secara teknis, Anda tidak memerlukan apa pun selain editor teks untuk menggunakan alur kerja ini. Dukungan dalam IDE juga bagus, terutama kemampuan untuk menampilkan daftar ulasan di bagian bawah.

Masih ada beberapa kekurangan:

• Ini berfungsi dengan baik untuk tim yang sangat kecil, tetapi tim yang lebih besar akan membutuhkan pelacakan atas apa yang ditinjau, kapan, oleh siapa dan dengan hasil apa. Meskipun Anda sebenarnya memiliki jenis pelacakan ini (kontrol versi memungkinkan untuk mengetahui semua itu), sangat sulit untuk digunakan dan mencari, dan akan sering membutuhkan pencarian manual atau semi-manual melalui revisi.

• Saya tidak percaya bahwa resensi memiliki umpan balik yang cukup dari peserta yang ditinjau untuk mengetahui bagaimana poin yang ditinjau benar-benar diterapkan .

  Bayangkan situasi berikut. Alice mengulas untuk pertama kalinya kode Eric. Dia memperhatikan bahwa Eric, seorang pengembang muda, menggunakan sintaksis yang bukan yang paling deskriptif dalam bahasa pemrograman yang sebenarnya digunakan.

  Alice menyarankan sintaksis alternatif, dan mengirimkan kode kembali ke Eric. Dia menulis ulang kode menggunakan sintaks alternatif ini yang dia percayai dengan benar, dan menghilangkan // BLAkomentar yang sesuai .

  Minggu berikutnya, dia menerima kode untuk ulasan kedua. Apakah dia bisa benar-benar ingat bahwa dia membuat komentar ini selama ulasan pertamanya, untuk melihat bagaimana Eric menyelesaikannya?

  Dalam proses peninjauan yang lebih formal, Alice dapat segera melihat bahwa dia membuat komentar, dan melihat perbedaan kode yang relevan, untuk mengetahui bahwa Eric salah mengerti sintaks yang dia katakan kepadanya.

• Orang masih manusia. Saya cukup yakin bahwa beberapa komentar itu akan berakhir dalam kode produksi, dan beberapa akan tetap menjadi sampah sementara sudah usang sama sekali .

  Tentu saja, masalah yang sama ada dengan komentar lain; misalnya ada banyak komentar TODO dalam produksi (termasuk yang paling berguna: "TODO: Komentar kode di bawah ini."), dan banyak komentar yang tidak diperbarui ketika kode yang sesuai.

  Misalnya, penulis asli kode atau pengulas mungkin akan pergi, dan pengembang baru tidak akan mengerti apa yang dikatakan oleh ulasan, sehingga komentar akan tetap selamanya, menunggu bahwa seseorang akan terlalu berani untuk menghapusnya atau untuk benar-benar memahami apa yang ia mengatakan.

• Ini tidak menggantikan tinjauan tatap muka (tetapi masalah yang sama juga berlaku untuk ulasan lain yang lebih formal yang tidak dilakukan tatap muka).

  Terutama, jika tinjauan awal memerlukan penjelasan, pengulas dan penerima ulasan akan memulai semacam diskusi . Tidak hanya Anda akan menemukan diri Anda dengan komentar BLA besar, tetapi diskusi itu juga akan mencemari log kontrol versi .

• Anda juga dapat mengalami masalah kecil dengan sintaks (yang juga ada untuk komentar TODO). Misalnya, bagaimana jika komentar panjang "// BLA" muncul pada beberapa baris, dan seseorang memutuskan untuk menulisnya dengan cara ini:

  // BLA This is a very long comment which is way beyond 80 characters, so it actually
  // fills more then one line. Since the next lines start with slashes, but not "BLA"
  // keyword, the IDE may not be able to show those lines, and display only the first one.
  

• Dan akhirnya sebagai catatan minor dan sangat pribadi: jangan pilih "BLA" sebagai kata kunci. Kedengarannya jelek. ;)

Saya akan melengkapi komentar dalam kode dengan dokumen pendamping. Ini akan merangkum temuan dan hidup setelah komentar dihapus. Keuntungan dari ini adalah:

• kekompakan. Jika orang tersebut secara rutin gagal memeriksa bahwa sebuah pointer yang dikirimkan bukan nol (atau kesalahan pemula yang umum lainnya dalam bahasa yang Anda gunakan), reviewer dapat meninggalkan lusinan komentar REV ke efek itu, dan dalam dokumen itu dapat mengatakan " Saya menemukan 37 tempat di mana pointer tidak diperiksa terlebih dahulu "tanpa mendaftar semuanya
• tempat untuk pujian. Komentar seperti REV this is a nice designsepertinya agak aneh, tetapi ulasan kode saya sering menyertakan persetujuan serta koreksi
• interaktivitas. Komentar sampel Anda adalah "mengapa Anda melakukan ini?" dan itu sangat khas. Pendekatan khusus komentar tidak mendukung percakapan. Orang tersebut dapat mengubah kode mereka dan menghapus komentar, atau menghapus komentar. Tetapi "mengapa kamu melakukan ini?" dan "tolong ubah ini, itu salah" bukan hal yang sama.
• menyimpan catatan. Peninjau selanjutnya dapat memeriksa apakah kode itu benar-benar diubah, atau komentarnya baru saja dihapus. Mereka juga dapat memeriksa bahwa komentar telah "diterima" dan pengembang tidak lagi membuat kesalahan yang sama dalam ulasan berikutnya.

Saya juga akan menggunakan item pekerjaan untuk melakukan review dan menanggapi review, dan mengaitkan checkin dengannya. Itu membuatnya mudah untuk menemukan komentar di set perubahan lama, dan untuk melihat bagaimana masing-masing ditangani dalam set perubahan lain.

Yang lain berbicara tentang keterbatasan pendekatan ini. Anda menyebutkan bahwa alat seperti gerrit sulit dipasang - saya sarankan Anda melihat phabricator (http://www.phabricator.com). Ini adalah sistem peninjauan kode yang telah digunakan Facebook selama bertahun-tahun, dan baru-baru ini bersumber terbuka. Tidak sulit untuk menginstal, memiliki alur kerja yang sangat baik, dan menyelesaikan semua masalah yang disebutkan dalam komentar lainnya.