Bagaimana saya bisa berurusan dengan anggota tim yang tidak suka membuat komentar dalam kode?

Salah satu anggota tim saya secara konsisten menghindari membuat komentar dalam kodenya.

Kode-nya tidak mendokumentasikan diri sendiri, dan programmer lain kesulitan memahami kode-nya.

Saya telah memintanya beberapa kali untuk mengomentari kodenya, namun dia hanya memberikan alasan atau klaim bahwa dia akan melakukannya nanti. Kekhawatirannya adalah bahwa menambahkan komentar akan memakan terlalu banyak waktu dan menunda proyek.

Argumen apa yang bisa saya sampaikan kepadanya untuk meyakinkan dia untuk mendokumentasikan kodenya dengan baik?

Pada catatan itu, apakah saya salah untuk fokus pada komentar kode atau ini merupakan indikasi masalah yang lebih besar yang harus diatasi?

Komentar saja tidak menghasilkan kode yang lebih baik, dan hanya mendorong "lebih banyak komentar" cenderung memberi Anda sedikit lebih banyak daripada /* increment i by 1 */komentar gaya.

Jadi tanyakan pada diri Anda mengapa Anda ingin komentar itu. "Ini praktik terbaik" tidak dihitung sebagai argumen kecuali Anda mengerti alasannya.

Sekarang, alasan paling mencolok untuk menggunakan komentar adalah agar kodenya lebih mudah dipahami, dan ketika orang-orang mengeluhkan kurangnya komentar, mereka adalah burung beo yang tidak mengerti, atau mereka kesulitan memahami kode yang mereka kerjakan.

Jadi jangan mengeluh tentang komentar yang hilang: mengeluh tentang kode yang tidak dapat dibaca. Atau lebih baik lagi, jangan mengeluh, terus bertanya tentang kode. Untuk apa pun yang Anda tidak mengerti, tanyakan orang yang menulisnya. Anda harus tetap melakukan itu; dengan kode yang tidak dapat dibaca, Anda hanya akan bertanya lebih banyak. Dan jika Anda kembali ke sepotong kode nanti, dan Anda tidak yakin Anda ingat dengan benar apa yang dilakukannya, ajukan pertanyaan yang sama lagi.

Jika komentar dapat memperbaikinya, dan kolega Anda memiliki otak yang berfungsi, dia akan menyadari bahwa mengomentari kode jauh lebih mudah daripada meminta Anda berkeliling untuk menanyakan pertanyaan bodoh sepanjang waktu. Dan jika Anda tidak dapat mengajukan pertanyaan, maka mungkin kode itu sudah dapat dibaca dengan sempurna, dan Andalah yang salah - lagi pula, tidak semua kode membutuhkan komentar.

Di depan keterampilan orang, hindari terdengar merendahkan atau menuduh dengan cara apa pun; serius dan jujur ​​tentang pertanyaan Anda.

Saya telah bertemu banyak devs yang kesulitan menulis kode dokumentasi mandiri atau komentar yang bermanfaat. Orang-orang seperti ini seringkali kurang memiliki disiplin diri atau pengalaman untuk melakukannya dengan benar.

Yang tidak pernah berhasil adalah, "memberi tahu mereka untuk menambahkan lebih banyak komentar". Ini tidak akan meningkatkan disiplin diri atau pengalaman mereka. IMHO, satu-satunya hal yang mungkin berhasil adalah sering melakukan tinjauan kode & sesi refactoring. Ketika seorang dev telah menyelesaikan tugas, izinkan dia untuk menjelaskan bagian mana pun dari kode yang tidak Anda mengerti. Segera refactor atau dokumentasikan kode sedemikian rupa sehingga Anda berdua akan mengerti 6 bulan kemudian.

Lakukan ini selama beberapa bulan, setidaknya dua kali seminggu. Jika Anda cukup beruntung, devs lain akan belajar melalui sesi ini sehingga Anda dapat mengurangi frekuensi ulasan.

Saya terkejut belum ada yang menyebutkan ulasan kode. Lakukan review kode! Ketika dia memiliki kualitas buruk, jangan hanya mengatakan "tambahkan komentar". Terus-menerus ajukan pertanyaan dan minta dia memberi tahu Anda apa yang dilakukan kode dan mengapa. Ambil catatan. Kemudian, di akhir ulasan kode berikan dia salinan catatan dan katakan padanya untuk membuat pertanyaan Anda cukup jelas. Entah dengan komentar lagi atau dengan hanya refactoring kodenya untuk membuatnya lebih berkualitas (lebih disukai yang terakhir bila mungkin)

Ini tergantung pada kode yang dihasilkan oleh pekerja tim Anda. Jika Anda membaca buku Kode Bersih dari Paman Bob Anda akan menemukan bahwa dia sebenarnya lebih suka untuk tidak menambahkan komentar ke kode. Jika kode itu sendiri dapat dibaca sebagaimana mestinya, maka hampir tidak ada kebutuhan untuk komentar.

Jika bukan itu masalahnya, atau Anda memerlukan komentar karena beberapa kebijakan yang tidak dapat dinegosiasikan, maka pertanyaan utamanya adalah apakah hanya Anda yang ingin dia menulis komentar, atau apakah itu seluruh tim atau tim / proyek pemimpin. Jika itu hanya Anda, maka Anda harus berbicara dengan kolega Anda yang lain untuk mencari tahu mengapa itu mungkin bukan masalah besar sama sekali.

Jika pemimpin proyek tidak memiliki komentar Anda juga dapat meminta mereka sebagai bagian dari kelengkapan , yaitu jika kode yang dikirimkan kurang komentar pekerjaan belum selesai. Dia mungkin tidak melanjutkan untuk melakukan pekerjaan lain, sampai pekerjaannya saat ini selesai dan untuk itu diperlukan komentar. Namun, perlu diingat bahwa pemaksaan semacam ini kemungkinan besar akan menghasilkan komentar yang mengerikan (berharap banyak pengulangan-of-code-comments).

Satu-satunya cara yang layak dalam pendapat saya yang sederhana adalah dengan mendiskusikan keuntungan aktual yang Anda dan semua orang dapatkan dari komentar. Jika dia tidak memahaminya hanya dengan diskusi, selalu ada jalan yang sulit: alih-alih membiarkan mereka menulis kode baru, minta mereka mengerjakan kode yang ada. Jika memungkinkan Anda harus menemukan mereka dua area kerja yang berbeda - satu dengan komentar bermanfaat yang tepat dan lainnya tanpa komentar. Harus membaca kode non-komentar orang lain yang tidak dapat dibaca adalah pembuka mata sehubungan dengan pekerjaan Anda sendiri.

Kita semua pernah ke sana dan marah kepada penulis asli dari beberapa sumber karena bekerja sangat ceroboh. Ini adalah refleksi tambahan bahwa kita masing-masing adalah penulis yang membuat Anda sadar bahwa Anda harus peduli dengan keterbacaan - karenanya, jangan lupa untuk mendiskusikan hasilnya dengan kolega Anda kemudian untuk mempromosikan refleksi ini.

Jika Anda memiliki karyawan yang tidak dapat mengikuti instruksi, tegurlah dia, dan pastikan itu jelas tidak akan membantu kariernya maju. Konsistensi dalam gaya pengkodean sangat penting untuk sebuah tim, dan jika semua orang menulis komentar dan yang ini tidak, itu akan merusak gaya pengkodean.

Yang mengatakan, Anda mungkin bisa membantunya. Dalam pengalaman saya, ketika seseorang memprotes bahwa berkomentar membutuhkan terlalu banyak waktu ada hambatan psikologis seperti ...

1. Dia sadar diri tentang kode / pilihan desainnya dan tidak ingin mengeluarkannya dalam bentuk prosa. (Ulasan kode dapat membantu untuk meningkatkan kepercayaan diri seseorang sebanyak menghancurkannya.)
2. Dia bekerja sangat linier dan tidak banyak berpikir ke depan. Mengomentari itu menyakitkan karena memaksanya untuk mengeluarkan kode langsung yang akan ditulisnya dari ingatannya yang sedang bekerja untuk menyusun maksudnya dengan cara yang berbeda. (Jika ini benar, komentar menjadi sangat penting untuk kualitas kodenya.)
3. Secara historis orang tidak mengerti komentarnya.

Penting bagi seorang programmer untuk menyadari bahwa komentar seperti tes: Mereka tidak hanya untuk digunakan di masa depan - Mereka adalah untuk programmer itu sendiri. Mereka memaksanya untuk berpikir secara berbeda tentang pendekatannya.

Semua ini bukan pengganti CI, tes, atau ulasan kode. Itu hanya salah satu dari banyak bagian penting pengkodean yang, dengan sendirinya, bukan menulis kode.

Dapatkan perangkat lunak peninjau kode, dan gunakan dengan baik.

Kami menggunakan Kiln, dan kami menyukainya. Kami memiliki kebijakan bahwa setiap perubahan harus ditinjau (meskipun kami mengizinkan dev untuk menaikkan / menyetujui ulasan untuk mereka sendiri pada tag dan penggabungan tanpa konflik (meskipun sebagian besar dari kita menggunakan rebaseif); dengan cara ini kita dapat dengan cepat melihat perubahan tanpa ulasan).

Kode yang tidak jelas adalah alasan peninjauan kode ditolak. Tidak masalah apakah perbaikannya adalah komentar atau kode yang lebih jelas, tetapi peninjau harus dapat memahaminya. Beberapa devs lebih suka menulis ulang kode, tetapi yang lain (termasuk saya sendiri) sering merasa lebih mudah untuk mengekspresikan niat dalam komentar (kode dapat dengan mudah menunjukkan apa yang dilakukannya, tetapi lebih sulit untuk menunjukkan apa yang harus dilakukan).

Jika ada pertanyaan tentang kejelasan kode, peninjau selalu menang. Tentu saja penulis memahaminya, karena mereka yang menulisnya. Itu harus jelas bagi orang lain.

Dengan menggunakan perangkat lunak seperti Kiln, tidak ada perubahan yang diabaikan. Semua orang di tim dev saya lebih suka dengan cara ini. Perangkat lunak peninjauan kode telah berdampak besar pada kualitas kode kami, dan kualitas aplikasi :-)

Sangat mudah bagi devs untuk bersikap defensif dengan ulasan yang ditolak saat pertama kali memperkenalkan perangkat lunak, tetapi menurut pengalaman saya, tidak butuh waktu lama bagi mereka untuk menyadari bahwa segala sesuatunya lebih baik dengan cara ini dan merangkulnya :-)

Sunting: Juga patut dicatat, kami berusaha agar devs tidak menjelaskan kode samar secara verbal atau dalam komentar dalam ulasan. Jika ada sesuatu yang tidak jelas, tempat terbaik untuk menjelaskannya adalah dalam kode (dalam komentar, atau dengan refactoring), lalu tambahkan perubahan baru ke ulasan yang sama.

Menarik, bahwa keterbacaan sebagaimana diterapkan pada bahasa alami diukur dengan kecepatan membaca dan pemahaman. Saya kira aturan sederhana memang bisa diadopsi, jika komentar kode tertentu tidak meningkatkan properti ini, itu bisa dihindari .

Kenapa berkomentar?

Meskipun, komentar kode adalah bentuk dokumentasi yang disematkan, ada beberapa cara dalam bahasa pemrograman kelas atas untuk menghindari pemrograman yang "terlalu banyak didokumentasi" (dari kode yang bermakna) dengan menggunakan elemen-elemen dari bahasa itu sendiri. Ini juga merupakan ide yang buruk untuk mengubah kode menjadi daftar dari buku teks pemrograman, di mana pernyataan individu secara harfiah dijelaskan dalam cara yang hampir tautologis (ingat contoh kenaikan "/ * oleh 1 * /" dalam jawaban yang sudah disediakan), membuat komentar seperti itu relevan hanya untuk programmer yang tidak berpengalaman dengan bahasa.

Meskipun demikian, niat untuk mencoba mengomentari kode "yang tidak terdokumentasi" (tetapi tidak berarti) itulah yang benar-benar "sumber segala kejahatan". Keberadaan kode "yang tidak didokumentasikan" adalah pertanda buruk - baik itu kekacauan yang tidak terstruktur, atau peretasan aneh dari tujuan mistis yang hilang. Jelas, nilai kode semacam itu setidaknya dipertanyakan. Sayangnya selalu ada contoh, ketika memang lebih baik untuk memasukkan komentar ke dalam bagian (secara visual dikelompokkan) baris kode daripada membungkusnya menjadi subrutin baru (pikiran "konsistensi bodoh" yang "adalah hobgoblin dari pikiran kecil") .

Pembacaan kode! = Komentar kode

Kode yang dapat dibaca tidak membutuhkan penjelasan oleh komentar. Di setiap tempat tertentu dalam kode selalu ada konteks tugas yang harus dicapai oleh kode khusus ini. Jika tujuan tidak ada dan / atau kode melakukan sesuatu yang misterius = hindarilah dengan cara apa pun. Jangan biarkan peretasan aneh mengisi kode Anda - ini adalah hasil langsung dari penggabungan teknologi kereta dengan kurangnya waktu / minat untuk memahami dasar-dasarnya. Hindari kode mistik dalam proyek Anda!

Di sisi lain, program yang dapat dibaca = kode + dokumentasi dapat berisi beberapa bagian komentar yang sah, misalnya untuk memfasilitasi pembuatan dokumentasi "komentar ke API".

Ikuti standar gaya kode

Cukup lucu pertanyaannya bukan tentang mengapa berkomentar kode, ini tentang kerja tim - bagaimana menghasilkan kode dengan gaya yang sangat disinkronkan (yang orang lain dapat membaca / mengerti). Apakah Anda mengikuti standar gaya kode di perusahaan Anda? Tujuan utamanya adalah untuk menghindari penulisan kode yang memerlukan refactoring, terlalu "pribadi" dan "subyektif" ambigu. Jadi saya kira, jika seseorang melihat perlunya menggunakan gaya kode, ada alat yang serius bagaimana menerapkannya dengan benar - dimulai dengan mendidik orang dan berakhir dengan otomatisasi untuk kontrol kualitas kode (banyak serat, dll) dan (revisi) kontrol terintegrasi) sistem peninjauan kode.

Menjadi penginjil pembacaan kode

Jika Anda setuju bahwa kode dibaca lebih sering daripada yang tertulis. Jika ekspresi ide dan pemikiran yang jelas jelas penting bagi Anda, tidak peduli bahasa apa yang digunakan untuk berkomunikasi (matematika, kode mesin atau bahasa Inggris kuno) .. Jika misi Anda adalah untuk menghilangkan cara berpikir alternatif yang membosankan dan jelek .. (maaf , yang terakhir adalah dari "manifes" lain) .. mengajukan pertanyaan, memulai diskusi, mulai menyebarkan pemikiran buku tentang pembersihan kode (mungkin bukan hanya sesuatu yang mirip dengan pola desain Beck, tetapi lebih seperti yang telah disebutkan oleh RC Martin ) yang membahas ambiguitas dalam pemrograman. Lebih jauh pergi bagian poin-poin ide-ide kunci (dikutip dari buku O'Reilly tentang keterbacaan)

• Sederhanakan penamaan, komentar, dan pemformatan dengan tips yang berlaku untuk setiap baris kode
• Perbaiki loop, logika, dan variabel program Anda untuk mengurangi kompleksitas dan kebingungan
• Menyerang masalah di tingkat fungsi, seperti mengatur ulang blok kode untuk melakukan satu tugas sekaligus
• Tulis kode uji efektif yang menyeluruh dan ringkas — serta dapat dibaca

Memotong "mengomentari", seseorang masih memiliki banyak (saya kira menulis kode yang tidak perlu komentar adalah salah satu latihan yang hebat!). Memberi nama pengidentifikasi yang secara semantik bermakna adalah awal yang baik. Selanjutnya, susun kode Anda dengan mengelompokkan operasi yang terhubung secara logis ke dalam fungsi dan kelas. Dan seterusnya. Programmer yang lebih baik adalah penulis yang lebih baik (tentu saja, dengan asumsi keterampilan teknis lain yang diberikan).

Apakah saya salah untuk fokus pada komentar kode atau ini merupakan indikasi masalah yang lebih besar yang harus diatasi?

Agak. Kode hebat tidak perlu komentar. Namun seperti yang Anda katakan, kodenya tidak mendokumentasikan diri sendiri. Jadi saya tidak akan fokus pada komentar. Anda harus fokus pada peningkatan keterampilan dan keahlian pengembang Anda.

Jadi bagaimana caranya? Saran Doc Brown tentang ulasan / sesi refactoring adalah ide yang bagus. Saya menemukan pemrograman pasangan bahkan lebih efektif, tetapi mungkin juga jauh lebih sulit untuk diterapkan.

Pertama-tama, saya sarankan Anda membahas kembali pendekatan Anda tentang komentar.

Jika itu adalah komentar dokumentasi di tingkat API (nanti akan diketahui publik), maka pengembang ini tidak melakukan tugasnya. Tetapi untuk semua komentar lain, berhati-hatilah.

Dalam sebagian besar kasus yang saya temui, komentar itu jahat. Saya akan merekomendasikan membaca bab kode komentar "Clean code" oleh Robert Martin untuk mendapatkan pemahaman yang baik mengapa.

Komentar melukai kode Anda dalam beberapa cara:

1) Mereka sulit dipertahankan. Anda harus bekerja ekstra saat melakukan refactoring; jika Anda mengubah logika yang dijelaskan dalam komentar, Anda perlu mengedit komentar juga.

2) Mereka sering berbohong. Anda tidak dapat mempercayai komentar dan harus membaca kodenya. Yang menimbulkan pertanyaan: mengapa Anda membutuhkan komentar sama sekali?

// this method returns the sum of 'a' and 'b'
public int GetHash(int a, int b)
{
    //the calculation of the hash
    int result = a*b;
}

(Hash bukan jumlah tetapi produk.)

3) Komentar mengacaukan kode, dan sangat jarang menambah nilai.

Solusi saya: Daripada menambahkan lebih banyak komentar, cobalah untuk menghilangkannya sama sekali!

Jika anggota tim mengalami kesulitan memahami kode anggota tim lain (karena alasan apa pun); maka anggota tim tersebut harus dapat mengetahui siapa yang menulis kode asli (sistem kontrol revisi yang waras) dan harus didorong untuk meminta penulis kode untuk menjelaskannya secara langsung (misalnya berjalan ke meja mereka, duduk dan diskusikan).

Dalam hal ini, jika kurangnya komentar adalah masalah maka orang yang tidak cukup mengomentari kode mereka akan menghabiskan banyak waktu untuk menjelaskan apa yang telah mereka lakukan; dan (jika mereka cerdas) akan mulai menambahkan komentar untuk menghindari menghabiskan waktu pada semua penjelasan itu.

Perhatikan bahwa mendorong anggota tim untuk saling bertanya penjelasan berharga karena alasan lain. Sebagai contoh, mungkin seorang anggota tim kurang berpengalaman dan dapat belajar hal-hal dari anggota tim yang lebih berpengalaman.

Sebagian besar, dengan mendorong anggota tim untuk saling bertanya penjelasan Anda membuat sistem self-balancing; di mana anggota tim yang berbeda "menyesuaikan otomatis" satu sama lain.

Ini sebagian besar merupakan perpanjangan dari jawaban tdammers, tetapi melakukan review kode secara berkala.

Memintanya (dan pengembang lainnya) duduk, menelusuri kode mereka, dan sedikit banyak bertahan di depan atasan dan rekan-rekan mereka akan membuat semua orang lebih baik pembuat kode dan akan menambah nilai nyata selama periode waktu yang relatif singkat. Dalam jangka pendek, itu akan memberi pengembang pertanyaan tidak ada alasan untuk, pada saat peninjauan, komentar dengan benar kodenya.

EDIT: Saya tidak yakin mengapa seseorang akan menurunkan saran saya - mungkin saya menerima begitu saja bahwa manfaat dari tinjauan kode adalah pengetahuan umum ... silakan lihat utas ini mengenai analisis komunitas terhadap praktik:

Apakah kode meninjau praktik yang baik?

Mengingat seringnya pandangan ekstrem tentang berkomentar, saya ragu untuk mempertimbangkannya.

Apa sajakah argumen yang bisa saya sampaikan bahwa jika Anda akan menulis kode (tidak dapat dibaca) yang harus didokumentasikan dengan baik?

Memahami cara menulis kode yang bisa dikelola dan dibaca membutuhkan waktu, latihan, dan pengalaman. Pemrogram yang tidak berpengalaman (dan sayangnya banyak yang berpengalaman) sering menderita Ikea Effect ( PDF ). Itu karena mereka membangunnya dan sangat akrab dengannya, dan mereka yakin kodenya tidak hanya bagus, tetapi juga dapat dibaca.

Jika orang tersebut adalah programmer hebat, maka sedikit jika ada dokumentasi yang diperlukan. Namun, sebagian besar programmer tidak hebat dan banyak kode mereka akan menderita di departemen "keterbacaan". Meminta programmer yang biasa-biasa saja atau sedang mengembangkan untuk "menjelaskan kode mereka" berguna karena memaksa mereka untuk melihat kode mereka dengan mata yang lebih kritis.

Apakah ini berarti "mendokumentasikan" kode mereka? Belum tentu. Contohnya, saya memiliki programmer yang sama dengan masalah ini di masa lalu. Saya memaksanya untuk mendokumentasikan. Sayangnya dokumentasinya tidak dapat dipahami seperti kodenya, dan tidak menambahkan apa pun. Dalam tinjauan kode retrospeksi akan lebih bermanfaat.

Anda (atau seorang delegasi) harus duduk dengan programmer ini dan menarik beberapa kode yang lebih lama. Bukan hal baru yang dia tahu dari hanya mengerjakannya. Anda harus memintanya untuk memandu Anda melalui kode dengan interaksi minimal. Ini juga bisa menjadi sesi "mendokumentasikan" yang terpisah, di mana ia akan menjelaskan secara tertulis kode-kodenya. Maka dia harus mendapatkan umpan balik tentang pendekatan yang lebih baik.

Sebagai tambahan ... beberapa dokumentasi kadang-kadang diperlukan terlepas dari seberapa bagus "keterbacaan" dari kode tersebut. API harus memiliki dokumentasi, operasi yang sangat teknis dan kompleks harus memiliki dokumentasi untuk membantu programmer dalam memahami proses yang terlibat (sering di luar domain pengetahuan programmer), dan beberapa hal seperti regex yang kompleks harus benar-benar mendokumentasikan apa yang Anda cocokkan.

Banyak proyek memerlukan dokumentasi kode: dokumen antarmuka, dokumen desain, ...

Beberapa proyek mensyaratkan bahwa dokumentasi semacam itu harus dimasukkan ke dalam komentar kode dan diekstraksi dengan alat-alat seperti Doxygen atau Sphinx atau Javadoc, sehingga kode dan dokumentasi tetap lebih konsisten.

Dengan begitu, pengembang diminta untuk menulis komentar yang berguna dalam kode dan tugas ini terintegrasi dalam perencanaan proyek.

Saya akan menyatakan apa yang sebagian besar jawaban dan komentar mengisyaratkan: Anda mungkin perlu mencari tahu masalah sebenarnya di sini daripada mencoba untuk mendorong solusi yang Anda rasakan.

Anda termotivasi untuk melihat komentar dalam kodenya; mengapa ? Anda memberi alasan; mengapa alasan itu begitu penting bagi Anda? Dia lebih termotivasi untuk melakukan sesuatu yang lain; mengapa ? Dia akan memberi alasan; mengapa alasan itu begitu penting baginya? Ulangi ini sampai Anda tiba pada tingkat di mana konflik benar-benar muncul, dan cobalah untuk menemukan solusi di sana yang dapat Anda jalani bersama. Saya berani bertaruh itu tidak ada hubungannya dengan komentar.

Jika Anda mengikuti standar pengkodean yang baik, akan ada jumlah minimum komentar yang diperlukan. konvensi penamaan penting. Nama metode dan nama variabel harus menggambarkan peran mereka ..

TL saya menyarankan saya untuk menggunakan lebih sedikit komentar. dia ingin kode saya harus dapat dimengerti dan bersifat deskriptif. contoh sederhana: nama variabel untuk tipe string yang digunakan untuk pola pencarian

   var str1:String="" //not uderstandable
   var strSearchPattern:String="" //uderstandable

Sukai jawaban ulasan kode, tetapi mungkin proses saya akan sedikit membantu juga.

Saya suka komentar, tapi saya hampir tidak pernah menambahkannya ke dalam kode pada pass pertama. Mungkin itu hanya gaya saya tetapi saya akan menekan bagian kode yang sama 3 sampai 5 kali selama pengembangan (refactoring, tes menulis, dll).

Setiap kali saya sedikit bingung atau setiap kali seseorang bertanya kepada saya tentang bagian kode saya berusaha memperbaikinya sehingga masuk akal.

Ini bisa sesederhana menambahkan komentar menghapus rangkaian operasi yang membingungkan ke dalam fungsinya sendiri atau dapat memicu refactor yang lebih besar seperti mengekstraksi objek baru.

Saya menyarankan Anda mendorong semua orang dalam grup untuk "memiliki" bahwa kode mereka dapat dibaca oleh orang lain - ini berarti bahwa setiap kali seseorang bertanya kepada Anda tentang kode Anda, Anda berkomitmen untuk melakukan perubahan - atau lebih baik lagi berpasangan dengan itu seseorang untuk melakukan perubahan saat itu!

Serius mempertimbangkan mendorong untuk ini sebagai bagian dari "Kontrak Tim" Anda (Dan jelas membuat kontrak jika Anda tidak memilikinya) - dengan cara itu semua orang telah menyetujuinya dan Anda memilikinya di dinding di suatu tempat sehingga tidak ada t ada pertanyaan tentang apa yang telah Anda setujui untuk lakukan.

Mungkin orang ini perlu diberi apresiasi terhadap disiplin pengkodean yang baik, dan mengapa penting bagi orang lain untuk dapat memahami kode yang ditulisnya.

Saya telah bekerja pada beberapa basis kode yang benar-benar mengerikan dalam karier saya, yang mana kode itu diorganisasikan dengan sangat buruk, nama-nama variabel sangat buruk, komentar sangat buruk atau tidak ada, sehingga basis kode itu mengganggu produktivitas saya. Anda tidak dapat bekerja untuk memperbaiki atau meningkatkan basis kode yang tidak Anda mengerti, dan jika itu ditulis dengan cara yang tidak dapat ditembus oleh pendatang baru maka mereka akan menghabiskan lebih banyak waktu untuk mencoba memahaminya daripada benar-benar mengerjakannya.

Tidak ada guru yang lebih baik dari pengalaman yang keras!

Setiap basis kode memiliki bit mengerikan yang bersembunyi di dalamnya, bagian dari sistem yang tidak ingin disentuh oleh siapa pun karena mereka takut merusak sesuatu, atau mereka tidak dapat melakukan pekerjaan yang berarti karena siapa pun yang menulis kode telah lama pergi dan mengambil pemahaman mereka kode dengan mereka. Jika kode itu tidak dikomentari dan tidak mendokumentasikan diri maka itu hanya memperburuk masalah.

Saya sarankan Anda menemukan sedikit basis kode Anda yang seperti itu, dan memberikan tanggung jawab pembuat kode Anda yang merepotkan. Beri dia kepemilikan atas itu, buat itu menjadi tanggung jawabnya, biarkan dia mempelajari rasa sakit yang sebenarnya dari mengerjakan kode yang tidak dapat dipertahankan karena itu tidak terdokumentasi dengan baik atau tidak mungkin untuk dipahami dalam waktu singkat. Setelah beberapa bulan mengerjakannya, saya yakin dia akan mulai datang.

Beri dia kode orang lain tanpa komentar dan minta dia untuk memahami kode itu. Mungkin dia mengerti pentingnya komentar yang tepat saat itu.

Apakah programmer ini melakukan beberapa pemeliharaan kode. Jika tidak, ia harus: memeriksa proyek tidak disukai yang Anda miliki dan memberikan pemeliharaannya kepadanya.

Biasanya itu adalah proyek yang didokumentasikan dengan buruk di mana Anda kehilangan jam berusaha memahami apa yang sedang terjadi untuk memperbaiki apa yang bisa mudah diperbaiki. Jika pengalaman seperti ini tidak membuatnya ingin up to date, dokumentasi yang benar dan bermanfaat tidak akan ada.

Dalam salah satu proyek masa lalu saya tidak ada lusinan komentar (algoritma, hasil atau beberapa JavaDoc dasar), jadi saya hanya memutuskan untuk membuat 130 masalah untuknya, email pemberitahuan tentang masing-masing masalah setiap 4 hari. Setelah 3 minggu dia memiliki 280 masalah, kemudian dia memutuskan untuk menulis komentar.

Komentar memiliki satu tujuan, dan hanya satu tujuan:

Mengapa kode ini melakukan hal ini?

Jika komentar tidak menjelaskan mengapa sesuatu itu terjadi, maka harus dihapus. Komentar tidak berguna yang mengacaukan kode kurang berguna, mereka secara aktif berbahaya.

Saya memiliki kebiasaan membuat komentar saya hal yang paling jelas dalam IDE saya. Mereka disorot dengan teks putih pada latar belakang hijau. Benar-benar menarik perhatian Anda.

Ini karena kode menjelaskan apa yang dilakukan sesuatu, dan komentar adalah alasan mengapa ia melakukannya. Saya tidak bisa cukup menekankan hal ini.

Contoh komentar yang bagus:

/* Must instantiate clsUser before trying to encrypt a password because the code to 
   encrypt passwords only uses strong encryption if that module is loaded. */

Contoh buruk:

/* instantiate clsUser */

Jika Anda menggunakan komentar sebagai "bagian" dari kode: Potong metode mammoth Anda menjadi fungsi-fungsi kecil yang bermanfaat, dan hapus komentar.

Jika Anda mengatakan apa yang Anda lakukan pada baris berikutnya: Buat kode penjelasan sendiri dan hapus komentar.

Jika Anda menggunakan komentar sebagai pesan peringatan: Pastikan Anda mengatakan alasannya.

Untuk melengkapi jawaban di sini, saya dapat menambahkan "Jika Anda menginginkannya dilakukan dengan benar, Anda harus melakukannya sendiri."

Maksud saya bukan menjadi "komentator kode utama", maksud saya menjadi panutan dalam mendemonstrasikan apa yang Anda ingin lakukan oleh pengembang lain ini. Mereka mengatakan menunjukkan lebih efektif daripada mengatakan . Jika Anda dapat menunjukkan manfaat dari komentar berkualitas, atau bahkan mentor pengembang lain ini (sejauh yang ia mau), Anda mungkin menemukan lebih banyak kesuksesan dalam adopsi komentar kode.

Demikian pula, di rumah ada beberapa pekerjaan rumah tangga yang tidak saya pedulikan. Namun tugas-tugas yang sama kebetulan adalah pekerjaan "kencing kesayangan" istri saya ... tugas yang harus dilakukan agar dia bahagia. Situasi yang sama berlaku sebaliknya. Saya pikir Anda mungkin harus menerima bahwa pengembang lain ini memiliki prioritas yang berbeda dari Anda, dan tidak akan setuju dengan Anda dalam segala hal. Solusi yang saya dan istri saya temukan adalah untuk tugas-tugas "mengencingi hewan peliharaan" kita hanya perlu melakukannya sendiri, bahkan jika itu berarti melakukan sedikit lebih banyak pekerjaan sendiri.

Sederhana: jika karyawan tidak memberikan komentar, katakan padanya untuk menekan shift+alt+jkomentar otomatis dalam setiap metode secara bersamaan dengan memasukkan kode. silakan lakukan revisi kode untuk menghindari masalah ini.