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


184

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?


109
Mengomentari demi komentar tidak membuat kode lebih baik. Jika kodenya dapat dimengerti (termasuk alasannya) tanpa komentar maka denda jika tidak berkomentar.
Martin York

63
Oh ya, dan ketika kerumitan beberapa kode meningkat tiga kali lipat untuk menyelesaikan kondisi balapan atau kebuntuan, jangan mengomentari itu! Biarkan orang memecahkan teka-teki mengapa kode harus seperti itu, dan mengapa itu pecah dengan cara yang misterius jika mereka membuat perubahan eksperimental. Setiap orang harus menjadi grandmaster catur konkurensi ...
Kaz

12
@Kaz Sarcasm (saya harap) tidak menerjemahkan dengan baik ke teks.
deworde

10
@deworde & artjom - ya, itu sarkasme. tidak, itu tidak terlihat sebersih mungkin, tapi itu jelas sarkasme.

17
mengikuti prinsip Dale Carnegie Anda harus mencoba memahami mengapa dia tidak ingin berkomentar .. Anda menyebutkan bahwa dia tidak ingin menunda proyek..jadi Anda dapat mengatakan kepadanya bahwa jika dia tidak berkomentar orang lain tidak akan dapat memahami kode dan yang selanjutnya akan menunda proyek .. ini pasti akan membantu ..
Anirudha

Jawaban:


431

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.


269
+1 untuk "jangan mengeluh tentang komentar yang hilang: mengeluh tentang kode yang tidak dapat dibaca."
Md Mahbubur Rahman

4
Bagaimana jika jawaban atas pertanyaan tentang kode ada di sepanjang baris "Apa yang telah Anda lakukan untuk memahaminya?"
Saul

40
+1: Mendorong nama fungsi yang dapat dibaca dapat memiliki manfaat tambahan ... Pada Tinjauan Kode: "Tidak dapat memahami apa yang dilakukan xg_jkhsfkasq". "Oh, itu menyiram buffer pakan utama, sekarang bisakah aku melepaskan?" "Tentu, tapi aku ragu untuk menyetujuinya sampai kamu mengganti nama fungsi flush_primary_buffer" "Ah, tapi itu juga membersihkan cache utama, sehingga nama itu akan menyesatkan" "ITULAH APA? Tidak menghapus cache itu, itu 'Akan mematikan sistem! Saat Anda mengubah logika itu, maukah Anda mengubah nama fungsi itu? "
deworde

18
Saya akan khawatir memberi kesan bahwa saya tidak dapat membaca kode. Seorang manajer non-teknis mungkin hanya memperhatikan bahwa saya terus-menerus meminta bantuan 'Bob' karena kode Bob terlalu canggih untuk saya. Itu berarti Bob adalah pengembang yang 'maju' dan saya belum siap untuk bekerja di levelnya.
Rob P.

5
@Rob P. Saya melihat ketakutan, tetapi jika Anda tidak dapat membaca kode dan diharapkan Anda akan mempertahankan kode tersebut, maka kode tersebut tidak ditulis dengan baik, atau Anda tidak cukup tahu. Jika Anda tidak cukup tahu, Anda perlu bertanya. Jika bertanya mengungkapkan bahwa kode itu hanya sulit dibaca, dorong untuk diperbaiki. Kuncinya adalah, jika Anda pergi ke jalur rekayasa sosial, untuk mencampurnya apakah Bob pergi ke meja Anda atau Anda pergi ke meja kerjanya, dan menjadi sangat aktif dalam menunjuk hal-hal. Lagi pula, seorang manajer non-teknologi tidak akan dapat memahami isi diskusi ...
deworde

114

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.


5
+1 ini adalah satu-satunya cara untuk benar-benar menerapkan perubahan menjadi kolega yang telah saya temukan, benar-benar duduk bersama mereka dan mengulas / memperbaiki di samping mereka. Jika Anda tidak dalam posisi untuk menolak tinjauan kode, ini bisa sulit. Kadang-kadang ketika Anda berada di tingkat menengah, Anda hanya perlu mengangkat masalah kepada para senior dan jika mereka tidak mendengarkan, singkirkan hidung Anda sampai Anda senior dan dapat memveto sampah seperti itu
Jimmy Hoffa

1
Ulasan kode & pemrograman pasangan adalah cara terbaik dalam pengalaman saya meningkatkan standar keseluruhan pengembang dalam sebuah tim. Ini tentang berbagi pengetahuan dan keterampilan dalam tim. Tanpanya Anda membuat pengembang belajar dengan cara yang sulit dan dengan asumsi mereka keluar dari perguruan tinggi dengan sempurna. Kurangnya praktik ini secara umum di industri mungkin adalah alasan mengapa ada begitu banyak pengembang dengan 10+ tahun pengalaman yang tidak dapat menulis kode yang dapat dibaca dan dikelola dengan baik.
Martin Brown

27

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)


2
+1 - Jika Anda harus mengajukan pertanyaan tentang bagian mana pun dari kode maka bagian itu perlu komentar atau refactoring sehingga pertanyaan itu tidak perlu ditanyakan oleh orang lain di masa mendatang.
Dunk

+1 Juga terkejut kode / ulasan rekan sangat rendah jawabannya. Menerapkan tinjauan kode tingkat tim (agar tidak memilih individu) dapat membantu menyelesaikan masalah (dan mungkin orang lain yang bahkan tidak Anda tahu Anda miliki :). Pada ekstremnya Anda dapat menerapkan kebijakan no-solo-push di mana Anda tidak diizinkan mendorong kecuali perubahan Anda telah ditinjau oleh anggota tim lain.
Chris Lee

@ChrisLee di kebijakan peninjauan kode perusahaan saya tidak ditegakkan secara teknis, tetapi ada kebijakan bahwa sebelum sebuah cerita dapat ditandai sebagai Ready For Test, itu harus ditinjau kode, tidak peduli siapa yang melakukan pekerjaan pengembangan. Sangat menarik karena harus melakukan review kode ketika CTO melakukan check-in meskipun lol
Earlz

18

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.


+1 untuk membahas keuntungan aktual dari komentar. Komentar dimaksudkan untuk menambah nilai pada kode sumber.
Sparky

1
Re: "pemaksaan semacam ini kemungkinan besar akan menghasilkan komentar yang mengerikan". Jika Anda tidak mengomentari kode Anda, maka mengisi kembali komentar setelah kode selesai hampir selalu akan menghasilkan komentar yang mengerikan apakah Anda percaya atau tidak. Ketika Anda membuat kode, itulah saatnya Anda tahu persis MENGAPA Anda melakukan sesuatu dengan cara tertentu. Itulah saatnya untuk memberi tahu orang lain. Jika Anda berkomentar setelah selesai, kemungkinan Anda bahkan tidak akan ingat apa yang Anda pikirkan ketika Anda menulis kode, sehingga Anda cenderung memberikan komentar yang tidak berguna hanya untuk memberikan komentar.
Dunk

3
selalu punya masalah dengan pendekatan buku itu. Komentar dapat sangat berguna dalam menjelaskan proses / logika bisnis (atau mengapa) yang tidak dapat dilakukan oleh kode bersih.
bharal

Sementara komentar dalam kode tidak perlu, setidaknya harus ada deskripsi metode, seperti Javadoc
Danubian Sailor

2
Clean Code adalah buku yang layak, tetapi tidak harus diperlakukan sebagai Injil. Anda harus menerapkan akal sehat dan memutuskan sendiri apa yang berhasil. Saya tidak setuju dengan saran pada komentar, karena bahasa pemrograman diarahkan untuk mengekspresikan bagaimana masalah dengan sedikit alasan mengapa. Saya sedang menulis kode untuk Google Shopping yang menambahkan kode negara ke SKU produk. Jelas apa yang dilakukan kode, tetapi kecuali Anda tahu bahwa Anda hanya dapat menggunakan kode produk yang sama sekali, bahkan di pasar yang berbeda, Anda tidak akan tahu mengapa saya melakukan ini. Komentar yang saya tambahkan mengklarifikasi.
GordonM

10

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.


3
Saya tidak berpikir ancaman akan efektif, mereka dapat dianggap sebagai intimidasi (bahkan jika itu bukan maksudnya) dan coders sebagai aturan cenderung membenci keputusan dari atasan dan dalam hal ini dia mungkin hanya gali lebih dalam lagi. Bisa jadi itu sebagai upaya terakhir, tetapi hanya sebagai upaya terakhir.
GordonM

@GordonM Apakah Anda pikir akan lebih baik untuk tidak memberi tahu karyawan ketika perilakunya tidak pantas, dan apa konsekuensi dari kelanjutan perilaku yang tidak pantas itu?
kojiro

Tidak mengatakan apa-apa sama sekali bukan ide yang baik jelas, tetapi mengancam orang hanya akan menumbuhkan iklim ketakutan, terutama karena hal yang relatif kecil seperti gaya berkomentar. Jika Anda menjelaskan kepadanya secara wajar mengapa tim menganggap komentar penting itu baik. Tetapi saya tahu jika seseorang mengancam saya dengan karung atas sesuatu yang relatif kecil saya akan lebih cenderung untuk mulai mencari pekerjaan lain sebagai gantinya.
GordonM

@ GordonM Saya benar-benar mengambil pengecualian terhadap implikasi bahwa apa yang saya katakan mengancam, tapi bagaimanapun, saya memperbaikinya.
kojiro

8

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.


4

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


Anda bisa menulis kode yang tidak perlu komentar hanya untuk bersenang-senang. Ini mungkin memang latihan yang hebat, tetapi tidak jika Anda perlu kembali ke kode dan tidak dapat benar-benar mengubah apa pun karena Anda tidak akan tahu mengapa fungsi ini bekerja karena mungkin ada beberapa klien yang menginginkannya seperti itu. Tentu saja Anda mungkin berada dalam proyek 1% yang mungkin didokumentasikan dan beralasan di luar proyek, tetapi bahkan kemudian ada keputusan yang Anda buat selama pengkodean yang tidak bisa didorong kembali ke dokumentasi. Dan terus terang ... Siapa yang membaca dokumentasi yang tidak ada dalam kode. Tentu saja bukan programmer ;-P.
Nux

1
Seorang insinyur yang baik peduli dengan keseluruhan sistem (termasuk dokumentasi non-codegenerated) - tetapi di sini kita, tentu saja, pengkodean pikiran secara umum .. Maksud saya adalah bahwa tidak memiliki pengidentifikasi dalam kode yang disebut foo , bar , tmpSomething2 dan IamJustTooSmartAssToCare sudah membaik situasi dan mengurangi keseluruhan kebutuhan untuk menjelaskan kode itu dan apa fungsinya. Kode harus ditulis dengan "mode berpikir" seperti API yang dirancang dengan baik yang dibaca, dipahami, digunakan kembali, dan dikelola oleh manusia. Terlalu banyak komentar dalam kode yang sulit dipahami adalah pertanda sangat buruk!
Yauhen Yakimovich

Pemrograman BTW / pengkodean segala jenis logika spesifik domain dalam bentuk HACK atau perbaikan bug "sementara" sebenarnya menghasilkan "HACK aneh" - segera setelah Anda memiliki banyak dari mereka yang terjepit di dalam kotak hitam - harapkan mereka untuk gagal dan balas menembak. Ini dapat dibenarkan oleh tenggat waktu dalam proyek "dunia nyata", dll. tetapi pada kenyataannya itu hanya perangkat lunak murah yang membutuhkan renovasi logika domain (atau mungkin mencari pekerjaan baru).
Yauhen Yakimovich

Saya setuju bahwa keterbacaan itu penting, yang saya tidak setuju adalah Anda sepertinya mengatakan "jika Anda menjadikan keterbacaan sebagai prioritas, Anda tidak perlu komentar". Itu tidak benar. Telah ada yang melakukannya. Memikirkan apa yang Anda lakukan tidak hanya berasal dari penamaan variabel dengan cara yang masuk akal. Lakukan itu tentu saja, tetapi juga tambahkan alasan dalam komentar (bahkan jika itu dalam bentuk bug / persyaratan / nomor cerita di beberapa sistem eksternal). Itu yang saya katakan.
Nux

"jika Anda menjadikan keterbacaan sebagai prioritas, Anda tidak perlu komentar" - ya inilah yang saya katakan (dan saya sadar ini sepertinya tidak mudah untuk dicapai). BTW Apakah Anda memiliki situasi ketika mempertahankan riwayat komit (kontrol versi) tidak cukup untuk mencerminkan "bug / persyaratan / nomor cerita"? Saya telah mempraktekkan komitmen yang agak panjang - bekerja untuk saya dan memungkinkan untuk menjaga kode kosong dari sejarah pengembangan..membuatnya kurang berkembang secara organik.
Yauhen Yakimovich

3

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.


Pair Programming adalah Ide yang luar biasa, memberikan wawasan kepada programmer lain tentang pengembangan kode sehingga mereka tahu apa yang sedang terjadi, membuat dua orang bertanggung jawab atas kode tersebut. itu juga memberikan kesempatan bagi salah satu dari keduanya untuk mengatakan bahwa sesuatu harus memiliki komentar karena itu tidak biasa atau sesuatu yang orang lain dapat ubah karena sepertinya ... "kebocoran memori", "kode buruk", dll. beberapa hal perlu dikomentari sehingga orang lain di masa depan tidak membatalkan sesuatu karena itu tidak terlihat benar.
Maleakhi

3

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!


4
Ini konyol. Saya harap tidak ada yang percaya bahwa gaya berkomentar yang buruk seperti itu sangat membantu. Tapi apakah Anda benar-benar percaya bahwa komentar harus tidak pernah digunakan?
jmk

1
Yap, ini adalah saran yang konyol, jika kode ini sangat mudah dibaca saya bisa mengerti beberapa komentar tetapi melihat komentar harus mengatakan mengapa metode ini melakukan apa itu dan di mana itu akan digunakan setelah Anda mendapatkan lebih dari beberapa kelas memang ada tanpa alasan tanpa komentar, mereka membantu semua orang.
DBlackborough

3
Yang penting untuk diingat adalah bahwa sementara semuanya masuk akal bagi Anda saat ini, orang lain harus menjaga kode Anda dalam 3 tahun. Jangan mengacaukannya.
xaxxon

4
@xaxxon Belum lagi apel itu meskipun orang itu mungkin Anda.
lembut

3
@mehaase - Bukan apa, bukan bagaimana, tapi mengapa alasan paling penting untuk menambahkan komentar ke kode.
Henk Langeveld

1

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.


1

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?


Ketika ruangan yang penuh dengan orang mulai menertawakan kode Anda yang tidak dapat dibaca, Anda akan mulai melakukan pekerjaan pengkodean dan komentar yang lebih baik. :) Saya seorang penganjur besar ulasan kode.
Evik James

1
Membuat orang menertawakan kode di depan rekan kerja yang lain bukanlah cara untuk melakukannya: - \
Danny Tuppeny

1
Jika orang-orang yang melakukan tinjauan kode lebih suka tertawa daripada bersikap konstruktif, mereka membutuhkan pelatihan sama seperti pengembang yang tidak dapat menulis kode yang dapat dibaca. Memberikan kritik yang konstruktif dan bukannya merendahkan adalah salah satu keterampilan sosial yang sering saya temukan kurang dimiliki oleh pengembang.
Martin Brown

1

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.


0

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.


6
Tidak, dengan demikian pengembang diminta untuk menulis beberapa komentar. Mereka kegunaan menurun dengan tekanan untuk menulis mereka, sering tenggelam di bawah nol ke wilayah aktif berbahaya (komentar tidak valid adalah lebih buruk daripada tidak ada komentar) jika kebijakan tersebut didorong kuat.
Jan Hudec

1
@ JanHudec - Saya setuju dengan Anda. Itu sebabnya beberapa kontrol harus ditetapkan. Pembuatan otomatis memastikan bahwa, misalnya, argumen fungsi dalam kode sama dengan komentar. Selain itu, memiliki satu PDF bukan direktori file sumber membuat dokumentasi lebih mudah dibaca (yaitu, lebih dapat ditinjau) oleh lebih banyak orang.
mouviciel

2
Yah, tidak, tidak. Bagaimana Anda akan melihat dalam .pdf, bahwa kode sebenarnya melakukan sesuatu yang secara subtil berbeda dari yang dikatakan deskripsi?
Jan Hudec

1
Mungkin pendapat saya bias oleh domain saya, perangkat lunak luar angkasa kritis di mana semuanya ditinjau, dikendalikan, diverifikasi, diuji dua atau tiga atau empat kali. Pembuatan dokumentasi secara otomatis tidak menekan ketidakkonsistenan tetapi membantu menguranginya.
mouviciel

Ya, Anda sangat bias. Dalam domain seperti itu masuk akal, di sebagian besar unit test cukup untuk QA dan mendokumentasikan setiap fungsi terakhir akan membuang-buang waktu.
Jan Hudec

0

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.


0

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

0

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.


0

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.


-1

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


12
Saya baru saja menghindari tombol -1 pada ini. Sebagian besar kode yang saya tulis memiliki sedikit komentar. Saya rasa orang-orang tidak mengeluh bahwa itu tidak dapat dimengerti dalam beberapa tahun terakhir. Dengan sedikit pengecualian, jika kode membutuhkan komentar untuk dipahami , maka tidak perlu komentar, perlu perbaikan untuk kejelasan. (Tentu saja, Anda harus mengasumsikan pemahaman dasar tentang sintaks bahasa. Hal-hal seperti, di C ++, jangan reinterpret_cast<>()menyimpang dari cara Anda hanya untuk menghindari penggunaan karena orang mungkin merasa membingungkan; dalam C #, jika ??melakukan apa yang Anda butuhkan, gunakan itu; dll.)
CVn

2
@ MichaelKjörling: Ini mungkin sangat bergantung pada jenis kode apa yang Anda tulis. Jika kode Anda bergantung pada karakteristik bahasa atau API yang tidak diketahui secara umum, atau Anda melakukan sesuatu dengan cara yang berlawanan dengan intuisi untuk menghindari bug yang tidak jelas yang membutuhkan waktu berjam-jam untuk Anda temukan, akan jauh lebih efektif untuk berkomentar tentang itu (mungkin termasuk tautan ke artikel) daripada mencoba membuat kode "jelas" tentang informasi latar belakang ini tanpa komentar.
LarsH

@ MichaelKjörling: Saya sangat termotivasi untuk mengatakan itu hari ini karena saya telah bergulat selama sebulan terakhir dengan API GIS yang mendalam. Fasilitas API sangat kompleks, dan tidak didokumentasikan secara menyeluruh. Kami terus-menerus mengalami kejutan, beberapa di antaranya membuat kami mundur beberapa hari. Mengharapkan orang lain (atau saya dalam 6 bulan) harus menemukan kembali nugget tersebut agar dapat bekerja secara efektif dengan kode kita akan sangat menyia-nyiakan waktu orang itu. Dan rahasia-rahasia itu umumnya tidak dapat didokumentasikan dengan komentar "peningkatan untuk kejelasan".
LarsH

@ LarsH Itu mungkin akan memenuhi syarat sebagai salah satu dari "sangat sedikit pengecualian" yang saya sebutkan dalam komentar saya. Saya tidak menentang berkomentar di mana itu sebenarnya menambah nilai ; tetapi bukan jumlah komentar yang membuat kode mudah atau sulit dibaca. Yang mengatakan, dengan API, saya akan lebih cenderung mendokumentasikan kebiasaan itu di tempat lain; katakanlah, dalam wiki atau serupa. Mungkin juga menambahkan tautan ke halaman yang relevan di sebelah setiap penggunaan. Dengan begitu, Anda tidak perlu mencari tempat lain yang menggunakan fitur tertentu API setiap kali kode tidak bekerja seperti yang Anda harapkan pada upaya pertama.
CVn

@ MichaelKjörling: disepakati secara umum. Apakah pengecualian ini jarang atau tidak tergantung pada domain yang Anda programkan, dan API yang harus Anda gunakan. Tautan / referensi baik untuk catatan yang berlaku secara umum, tidak hanya untuk situasi saat ini. Tidak ada yang menginginkan disertasi dalam kode itu sendiri.
LarsH

-1

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.


1
Pendekatan ini lebih disukai untuk membuat programmer berhenti daripada melatih mereka dengan cara yang tepat dalam melakukan sesuatu.
Martin Brown

-1

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.


-1

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.


-2

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.


1
Saya berpendapat bahwa menunjukkan kode yang lebih bersih / refactoring kode mereka menjadi lebih mudah dibaca menunjukkan perubahan yang lebih besar daripada menempatkan sekumpulan komentar ke dalam kode.
Makoto

Adakah yang bisa menjelaskan kepada saya apa yang tidak mereka sukai tentang ide saya ...?
M. Dudley

-6

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.


11
"Komentar otomatis"? Jadi dari situlah semua komentar "increment i by 1" itu berasal? IDE mana yang melakukan ini (jadi saya bisa menghindari pekerjaan di mana itu digunakan)?
CVn

Saya mencoba mengedit ini menjadi sesuatu yang dapat dibaca, tetapi saya tidak yakin apakah kata itu pertama kali harus koma sebelum atau sesudahnya. Apakah frasa membuat komentar terlebih dahulu atau yang pertama katakan dalam setiap metode ?
TRiG
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.