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


16

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.

Contoh kustom tugas-dari-komentar yang difilter di gerhana

Pertanyaan

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

Pertanyaan bagus tetapi tidak ada hubungannya dengan serbet - bukan judul yang bagus.
Markus

@ MarkJ bagaimana menamainya? Maksud saya kerajinan tangan, pondok, buatan sendiri. Di Rusia kami memiliki frasa "на коленке". Sesuatu yang tidak stabil, tidak ideal, seperti non-solid, tetapi berhasil.
gaRex

2
@ MarkJ, gaRex: bagaimana dengan judul baru ini? Jangan ragu untuk kembali jika Anda merasa tidak cocok untuk pertanyaan ini.
Arseni Mourzenko

@MainMa, tidak apa
gaRex

1
Atlassian Crucible pada dasarnya gratis untuk hingga 10 pengembang. Itu juga merupakan alat peninjau kode terbaik yang pernah saya gunakan. Pendekatan komentar layak tetapi dapat membuat sulit untuk melacak keadaan.
Andrew T Finnell

Jawaban:


14

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. ;)


"untuk mengetahui bagaimana poin yang direview benar-benar diterapkan" Ya :) Hanya kejujuran dari yang ditinjau. Di sini kita memiliki lebih banyak kebijakan, daripada alat.
gaRex

1
"people is people" Ya :( Kami sudah memiliki jutaan TODO ini. Mungkin hanya ditolak untuk memiliki fitur seperti itu di IDE?
gaRex

"mencemari log kontrol versi" Untuk ini semua pekerjaan ada di cabang fitur mandiri, yang kemudian tergencet & bergabung dalam pengembangan. Mungkin ini bisa dilakukan dengan kait sederhana di DVCS. Tapi seperti yang saya lihat semua kerumitan bergerak dari alat pengkodean kode ke IDE & DVCS.
gaRex

"masalah kecil dengan sintaks" Mungkin itu bukan masalah? REV itu hanya sebagai beberapa penanda untuk dengan cepat pergi dari panel.
gaRex

1
@gaRex: maka anggota tim Anda harus menggunakan email untuk menyetujui tanggal tatap muka ;-)
Doc Brown

4

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.


maka kita membutuhkan beberapa alat review kode yang baik. Pendekatan kami yang dijelaskan saat ini sebagian besar bersifat politis karena orang harus menemukan ethiquet dan mengikutinya.
gaRex

"kekompakan" - Saya pikir itu bisa dilakukan dengan satu komentar seperti "// REV Dude, kami memiliki 37 tempat di mana pointer tidak diperiksa terlebih dahulu, termasuk yang ini.
Tolongkan

"tempat untuk pujian" - juga memungkinkan, tetapi setelah squashing akan hilang :( Saya sudah melihat satu masalah - kami kehilangan riwayat ulasan saat squashing melakukan.
gaRex

"interaktivitas" - penulis dapat menjawab dalam komentar lain, di bawah inisial. Sama seperti gaya wikipedia.
gaRex

"orang bisa ... menghapus komentar" - ini masalah. +1
gaRex

2

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.


Wow! Kita perlu mencobanya bukan dari redmine kita yang indah.
gaRex

"gerrit" Saya menginstalnya - itu tidak terlalu sulit. Saya hanya gagal menggunakannya! Dan juga memiliki UI dan alur kerja yang jelek.
gaRex

@gaRex Kami menggunakan Reviewboard ( reviewboard.org ) secara paralel dengan Redmine. Mereka melayani tujuan yang berbeda sehingga tidak apa-apa. Dan Anda dapat mengatur RB untuk terhubung ke masalah Redmine ...
Johannes S.

@JohannesS. vcs mana yang Anda gunakan? Anda juga punya beberapa howto atau wiki siap tentang integrasi mereka? Senang memiliki yang seperti itu.
gaRex

@gaRex Maaf atas keterlambatan balasan. Kami menggunakan SVN, tetapi RB juga mendukung git (sebenarnya, orang RB menggunakan git sendiri). Saya sarankan untuk melihat situs web RB. Ada demo online yang tersedia (mis. Lihat demo.reviewboard.org/r/101 )
Johannes S.
Dengan menggunakan situs kami, Anda mengakui telah membaca dan memahami Kebijakan Cookie dan Kebijakan Privasi kami.
Licensed under cc by-sa 3.0 with attribution required.