it-swarm-id.com

"Komentar adalah bau kode"

Seorang rekan kerja saya percaya bahwa setiap penggunaan komentar dalam-kode (yaitu, bukan metode gaya javadoc atau komentar kelas) adalah (bau kode . Bagaimana menurut anda?

100
Fishtoaster

Hanya jika komentar menjelaskan apa yang dilakukan kode.

Jika saya ingin tahu apa yang terjadi dalam suatu metode atau blok, saya akan membaca kodenya. Saya berharap, bagaimanapun, bahwa setiap pengembang yang mengerjakan proyek tertentu setidaknya cukup akrab dengan bahasa pengembangan untuk membaca apa yang ditulis dan memahami apa yang dilakukannya.

Dalam beberapa kasus optimisasi ekstrem, Anda mungkin menggunakan teknik yang menyulitkan seseorang untuk mengikuti apa yang dilakukan kode Anda. Dalam kasus ini, komentar dapat dan harus digunakan untuk tidak hanya menjelaskan mengapa Anda memiliki optimasi seperti itu, tetapi apa yang dilakukan oleh kode. Aturan praktis yang baik adalah meminta orang lain (atau banyak orang lain) akrab dengan bahasa implementasi dan proyek melihat kode Anda - jika mereka tidak dapat memahami mengapa dan bagaimana, maka Anda harus mengomentari mengapa dan bagaimana caranya.

Namun, yang tidak jelas dalam kode adalah mengapa Anda melakukan sesuatu. Jika Anda mengambil pendekatan yang mungkin tidak jelas bagi orang lain, Anda harus memiliki komentar yang menjelaskan mengapa Anda membuat keputusan yang Anda lakukan. Saya akan curiga bahwa Anda mungkin bahkan tidak menyadari bahwa komentar diperlukan sampai setelah sesuatu seperti tinjauan kode, di mana orang ingin tahu mengapa Anda melakukan X daripada Y - Anda dapat menangkap jawaban Anda dalam kode untuk semua orang yang melihatnya di masa depan.

Namun, hal yang paling penting adalah mengubah komentar Anda ketika Anda mengubah kode Anda. Jika Anda mengubah algoritme, pastikan untuk memperbarui komentar dengan alasan Anda menggunakan algoritme X lebih dari Y. Komentar basi adalah bau kode yang lebih besar.

167
Thomas Owens

Ini sangat menjengkelkan untuk didengar saat ini, saya menghabiskan beberapa waktu akhir pekan ini untuk melihat kode yang sangat terkenal, sangat bersih, tidak diomentari yang mengimplementasikan algoritma penelitian (yang tidak dipublikasikan). Saya sangat akrab dengannya, orang yang duduk di sebelah saya adalah penemunya, dan kode itu ditulis beberapa tahun yang lalu oleh orang lain. Kita bisa nyaris mengikutinya.

Rekan kerja Anda tidak cukup berpengalaman, jelas.

110
Paul Nathan

Komentar harus menjelaskan mengapa, bukan bagaimana.

How jenis komentar biasanya lebih baik ditangani dengan menggunakan refactoring. Secara pribadi, saya biasanya menghindari komentar yang mendukung refactoring.

Sebelum:

# convert to cents
a = x * 100

# avg cents per customer 
avg = a / n

# add to list
avgs < avg
t += 1

setelah:

total_cents = total * 100
average_per_customer = total_cents / customer_count

track_average(average_per_customer)
75
Sam Saffron

Saya menyatakan rekan kerja Anda sesat! Di mana sepatu bot bakar sesat saya?

Mengomentari obsesif itu buruk dan sakit kepala, dan komentar bukan pengganti metode, kelas, variabel, dll. Namun terkadang menempatkan mengapa sesuatu adalah caranya bisa sangat berharga bagi si idiot miskin yang harus menjaga kode dalam enam bulan - terutama ketika si idiot miskin itu akhirnya menjadi Anda.

Beberapa komentar aktual dari kode yang saya kerjakan:


    // If this happens, somebody's been screwing around with the database definitions and
    // has removed the restriction that a given alarm may have only one entry in the 
    // notifications table.  Bad maintenance programmer!  Bad!  No biscuit!



    // If an alert is active on our side but inactive on theirs, that might mean
    // they closed the alert.  (Or that we just haven't told them about it yet.)  The
    // logic comes later; for now, we'll just compile it in a list.



    // If we know for a fact that an alarm isn't getting through, we're going to whine pretty
    // aggressively about it until it gets fixed.

32
BlairHippo

Idealnya, kode harus dikodekan dengan sangat baik sehingga harus bersifat explicative otomatis. Di dunia nyata, kita tahu bahwa kebutuhan kode juga sangat tinggi terkadang perlu dikomentari.

Yang harus Anda hindari adalah "redundansi kode komentar" (komentar yang tidak menambahkan apa pun ke kode):

i++; // Increment i by 1

Kemudian, jika ada desain dan dokumentasi kode yang baik (dan dipelihara/disejajarkan), berkomentar bahkan kurang berguna.

Tetapi dalam beberapa keadaan komentar dapat menjadi bantuan yang baik dalam pembacaan kode:

while( foo )
{
     if( dummy )
     {
     }
     else // !dummy
     {
     }
} // end while( foo )

Jangan lupa bahwa Anda harus menjaga dan tetap sinkron juga komentar ... komentar yang ketinggalan jaman atau salah bisa sangat menyebalkan! Dan, sebagai aturan umum, berkomentar terlalu banyak bisa menjadi gejala pemrograman yang buruk.

29
Wizard79

Mendefinisikan secara kategoris suatu metode atau proses sebagai "bau kode" adalah "bau fanatik". Istilah ini menjadi baru "dianggap berbahaya".

Harap diingat bahwa semua hal ini seharusnya menjadi pedoman.

Banyak dari jawaban lain memberikan nasihat yang baik tentang kapan komentar dibenarkan.

Secara pribadi saya menggunakan sangat sedikit komentar. Jelaskan tujuan dari proses yang tidak jelas dan serahkan ancaman kematian sesekali kepada siapa pun yang mungkin mempertimbangkan untuk mengubah hal-hal sendiri yang membutuhkan penyetelan berminggu-minggu.

Refactoring semuanya sampai anak TK dapat memahaminya sepertinya bukan penggunaan waktu Anda secara efisien, dan mungkin tidak akan berkinerja sebaik versi yang lebih ringkas.

Komentar tidak memengaruhi waktu berjalan, jadi satu-satunya masalah negatif yang perlu dipertimbangkan adalah pemeliharaan.

26
Bill

Masalah utama di sini adalah arti dari istilah "bau kode".

Banyak orang (termasuk Anda, saya kira) memahami bau kode sebagai sesuatu yang dekat dengan kesalahan atau setidaknya sesuatu yang perlu diperbaiki. Mungkin Anda menganggapnya sebagai sinonim dengan "anti-pola".

Ini bukan arti dari istilah!

Metafora bau kode berasal dari Wards Wiki , dan mereka menekankan:

Perhatikan bahwa CodeSmell adalah petunjuk bahwa sesuatu mungkin salah, bukan kepastian. Idiom yang sangat baik dapat dianggap sebagai CodeSmell karena sering disalahgunakan, atau karena ada alternatif sederhana yang berfungsi dalam banyak kasus. Menyebut sesuatu CodeSmell bukanlah serangan; itu hanya pertanda bahwa diperlukan pemeriksaan lebih dekat.

Jadi apa artinya komentar adalah bau kode: artinya ketika Anda melihat komentar, Anda harus berhenti sejenak dan berpikir: "Hmmm, saya merasakan petunjuk bahwa sesuatu dapat ditingkatkan". Mungkin Anda dapat mengubah nama variabel, melakukan "ekstrak metode" -mengevaluasi - atau mungkin komentar itu sebenarnya solusi terbaik.

Itulah artinya komentar menjadi bau kode.

EDIT: Saya baru saja meneliti dua artikel ini, yang menjelaskannya lebih baik daripada saya:

23
Rasmus Faber

Dalam beberapa kasus, tidak ada jumlah penamaan yang baik, refactoring dll dapat menggantikan komentar. Lihat saja contoh dunia nyata ini (bahasa adalah Groovy):

  response.contentType="text/html"
  render '{"success":true}'

Terlihat aneh, bukan? Mungkin kesalahan salin-tempel? Menangis untuk perbaikan bug?

Sekarang sama dengan komentar:

  // DO NOT TOUCH THE FOLLOWING TWO LINES; the ExtJS UploadForm requires it exactly like that!!!
  response.contentType="text/html"  // must be text/html so the browser renders the response within the invisible iframe, where ExtJS can access it
  render '{"success":true}'         // ExtJS expects that, otherwise it will call the failure handler instead of the succss handler
23
user281377

Saya pikir aturannya cukup sederhana: bayangkan orang asing melihat kode Anda. Anda mungkin akan menjadi orang asing dengan kode Anda sendiri dalam 5 tahun. Cobalah untuk meminimalkan upaya mental untuk memahami kode Anda untuk orang asing ini.

21

Ide yang bagus untuk mendapatkan komentar yang tepat adalah memulai dengan menulis komentar.

// This function will do something with the parameters, 
// the parameters should be good according to some rules.
myFunction(parameters)
{
    // It will do some things to get started.

    // It will do more with the stuff.

    // It will end doing things with the stuff.
}

Ini memungkinkan Anda untuk mengekstrak metode dengan mudah bahkan untuk menghilangkan komentar,
biarkan kodenya memberitahukan hal-hal ini! Lihat bagaimana ini ditulis ulang (potong/rekat) dengan cara yang sangat bagus:

// This function will do something with the parameters, 
// the parameters should be good according to some rules.
myfunction(parameters)
{
  var someThing = initializedWithSomething;

  doSomethingWith(someThing);

  doMoreWith(someThing);

  endDoingThingsWith(someThing);

  return someThing;
}

// This function will do some things to get started,
// the parameters should be good according to some rules.
doSomethingWith(parameters)
{
  parameters.manipulateInSomeWay();
  ... etc ...
}

... etc ...

Untuk hal-hal yang tidak dapat dipisahkan, jangan mengekstrak metode dan ketik kode di bawah komentar.

Inilah yang saya lihat sebagai cara yang berguna untuk terus mengomentari seminimal mungkin, tidak ada gunanya pergi mengomentari setiap baris ... Hanya mendokumentasikan satu baris jika ini tentang inisialisasi nilai magis atau di mana masuk akal.

Jika parameter terlalu banyak digunakan, maka itu haruslah anggota pribadi di kelas Anda.

11
Tamara Wijsman

Saya pikir jawabannya adalah yang biasa "Itu tergantung" satu. Mengomentari kode hanya untuk kode komentar adalah bau. Mengomentari kode karena Anda menggunakan algoritma yang tidak jelas yang merupakan urutan besarnya lebih cepat menyelamatkan programmer pemeliharaan (biasanya saya 6 bulan setelah saya menulisnya) setengah hari menyodok kode untuk menentukan apa yang dilakukannya.

10
Brandon
// Dear me in the future. Please, resolve this problem.

atau

// You think this code was written by somebody else. 
// No, it wasn't. You ([some name]) did it.
10
Zzz

Komentar kode jelas bukan "bau kode". Keyakinan ini biasanya berasal dari fakta bahwa komentar dapat menjadi basi (ketinggalan zaman) dan dapat sulit dipertahankan. Namun, memiliki komentar yang baik yang menjelaskan mengapa kode melakukan sesuatu dengan cara tertentu dapat (dan biasanya) penting untuk pemeliharaan.

Komentar yang baik membuatnya lebih mudah untuk memahami apa yang dilakukan kode dan, yang lebih penting, mengapa melakukannya dengan cara tertentu. Komentar dimaksudkan untuk dibaca oleh programmer dan harus jelas dan tepat. Sebuah komentar yang sulit dimengerti atau salah tidak jauh lebih baik daripada tidak memiliki komentar sama sekali.

Menambahkan komentar yang jelas dan tepat ke kode Anda berarti Anda tidak harus bergantung pada memori untuk memahami "apa" dan "mengapa" bagian kode. Ini paling penting ketika Anda melihat kode itu nanti, atau orang lain harus melihat kode Anda. Karena komentar menjadi bagian dari isi teks dari kode Anda, mereka harus mengikuti prinsip penulisan yang baik selain ditulis dengan jelas.

Untuk menulis komentar yang baik, Anda harus melakukan yang terbaik untuk mendokumentasikan tujuan kode (alasannya, bukan caranya) dan menunjukkan alasan dan logika di balik kode sejelas mungkin. Idealnya, komentar harus ditulis bersamaan dengan Anda menulis kode. Jika Anda menunggu, Anda mungkin tidak akan kembali dan menambahkannya.

Sams Teach Yourself Visual C # 2010 dalam 24 Jam , hlm 348-349.

8
Scott Dorman

Jika kode telah ditulis dengan cara tertentu untuk menghindari masalah yang ada di perpustakaan (baik perpustakaan pihak ketiga, atau perpustakaan yang datang dengan kompiler), maka masuk akal untuk berkomentar.
Juga masuk akal untuk mengomentari kode yang perlu diubah di versi masa depan, atau ketika menggunakan versi baru perpustakaan, atau ketika meneruskan dari PHP4 ke PHP5, misalnya.

6
kiamlaluno

Bahkan buku yang paling ditulis dengan baik masih memiliki judul pengantar dan bab. Komentar dalam kode yang terdokumentasi dengan baik masih berguna untuk menggambarkan konsep tingkat tinggi, dan menjelaskan bagaimana kode tersebut disusun.

6
munificent

Yang terhormat disebutkan adalah anti-pola:

Ini kesan saya bahwa kadang-kadang contoh lisensi FLOSS sering digunakan sebagai pengganti dokumentasi file. GPL/BSDL membuat teks pengisi yang bagus, dan setelah itu Anda jarang melihat blok komentar lainnya.

4
mario

Saya tidak setuju dengan gagasan bahwa menulis komentar untuk menjelaskan kode itu buruk. Ini sepenuhnya mengabaikan fakta bahwa kode memiliki bug. Mungkin jelas apa kode tidak tanpa komentar. Ini cenderung tidak jelas apa kode --- seharusnya harus dilakukan. Tanpa komentar bagaimana Anda tahu jika hasilnya salah, atau mereka digunakan secara tidak benar?

Komentar harus menjelaskan maksud dari kode, sehingga jika ada kesalahan, seseorang yang membaca komentar + kode memiliki peluang untuk menemukannya.

Saya biasanya menemukan diri saya menulis komentar inline sebelumnya Saya menulis kode. Dengan cara ini jelas apa yang saya coba tulis kode untuk dilakukan, dan mengurangi tersesat dalam suatu algoritma tanpa benar-benar tahu apa yang Anda coba lakukan.

4
Danny Tuppeny

Saya akan menjawab dengan pertanyaan saya sendiri. Dapatkah Anda menemukan bug dalam kode uncommented berikut?

tl; dr: Orang berikutnya yang menjaga kode Anda mungkin tidak seperti dewa.

 [org 0x7c00]

 main:
  mov ah, 0x0e
  mov bx, string
  call strreverse
  call print

 stop:
  jmp $

 strreverse:
  pusha
  mov dx, bx
  mov cx, 0

 strreverse_Push:
  mov al, [bx]
  cmp al, 0
  je strreverse_pop
  Push ax
  add bx, 1
  add cx, 1
  jmp strreverse_Push

 strreverse_pop:
  mov bx, dx

 strreverse_pop_loop:
  cmp cx, 0
  je strreverse_end
  pop ax
  mov [bx], al
  sub cx, 1
  add bx, 1
  jmp strreverse_pop_loop

 strreverse_end:
  popa
  ret

 print:
  pusha

 print_loop:
  mov al, [bx]
  cmp al, 1
  je print_end
  int 0x10
  add bx, 1
  jmp print_loop

 print_end:
  popa
  ret
 string:
  db 'Boot up', 0

 times 510 -( $ - $$ ) db 0
 dw 0xaa55
3
Ant

Komentar yang dimasukkan karena seseorang berpikir itu boleh saja memiliki 700 baris dalam satu metode adalah bau.

Komentar yang ada karena Anda tahu jika Anda tidak memberikan komentar, seseorang akan membuat kesalahan yang sama lagi-lagi bau.

Komentar dimasukkan karena beberapa alat analisis kode menuntutnya juga bau.

Orang yang tidak akan pernah memberikan komentar, atau bahkan menulis sedikit bantuan untuk pengembang lain juga merupakan bau. Saya kagum pada berapa banyak orang yang tidak akan menulis sesuatu, tetapi kemudian akan berbalik dan mengakui bahwa mereka tidak dapat mengingat apa yang mereka lakukan 3 bulan lalu. Saya tidak suka menulis dokumen, tetapi saya harus memberi tahu orang hal yang sama berulang-ulang bahkan lebih sedikit.

3
MIA

Anda harus menjaga keseimbangan antara kode dan komentar ... Biasanya saya mencoba menambahkan beberapa komentar yang melanjutkan satu blok kode. Bukan karena saya tidak akan dapat memahami kode (well, itu juga), tetapi karena saya dapat membaca lebih cepat kode saya sendiri dan menemukan bagian tertentu di mana hal-hal penting itu terjadi.

Bagaimanapun, kriteria pribadi saya adalah "ketika ragu, berkomentar". Saya lebih suka memiliki garis yang redundan daripada garis yang sepenuhnya samar yang saya tidak akan bisa mengerti. Saya selalu dapat menghapus komentar pada ulasan kode, setelah beberapa saat (dan biasanya saya lakukan)

Juga, komentar sangat membantu menambahkan "peringatan" seperti "Hati-hati! Jika format input bukan ASCII, kode ini harus diubah!"

2
Khelben

Saya pikir komentar kode mendapat awal yang sangat buruk untuk hidup. Saya tidak tahu tentang hari-hari ini, tetapi ketika saya pertama kali diajarkan pemrograman di sekolah saya mendapat tugas dari sifat "Menulis program yang mencetak angka satu hingga sepuluh pada baris yang terpisah. Pastikan Anda mengomentari kode Anda." Anda akan ditandai jika Anda tidak menambahkan komentar karena mengomentari kode Anda adalah HAL YANG BAIK.

Tapi apa yang bisa dikatakan tentang proses sepele seperti itu? Jadi Anda akhirnya menulis klasik

i++; // add one to the "i" counter.

hanya untuk mendapatkan nilai yang layak dan, jika Anda punya nous sama sekali, langsung membentuk pendapat komentar kode yang sangat rendah.

Mengomentari kode bukanlah HAL YANG BAIK. Ini hal yang perlu diperhatikan, dan Thomas Owens dalam jawaban teratas memberikan penjelasan yang sangat baik tentang situasi di mana itu perlu. Namun, situasi ini jarang muncul dalam penugasan jenis pekerjaan rumah.

Dalam banyak hal, menambahkan komentar harus dianggap sebagai pilihan terakhir, ketika apa yang perlu dikatakan tidak dapat dikatakan dengan jelas di bagian aktif dari bahasa pemrograman. Walaupun penamaan objek bisa basi, berbagai mekanisme manusia dan komputer kurang umpan balik membuatnya mudah untuk melupakan komentar dan akibatnya komentar menjadi basi lebih cepat daripada kode aktif. Karena alasan itu, di mana pilihan dimungkinkan, mengubah kode untuk membuatnya lebih jelas harus selalu lebih disukai daripada menjelaskan kode yang tidak jelas dengan komentar.

2
Alohci

Membaca ini saya teringat pada sesuatu yang pertama kali saya baca (dari daftar yang lebih panjang, diawetkan dengan mengambil fotokopi) beberapa dekade yang lalu:

Pemrogram sungguhan tidak menulis komentar - jika sulit untuk menulis itu harus sulit dibaca

Bau yang agak lebih tua.

2
Murph

Tentu saja komentar adalah bau kode ...

setiap programmer tahu kita semua akhirnya menjadi gila karena jumlah pekerjaan, debugging, atau sekadar kegilaan yang kita alami.

"Melakukan hal ini!" kata manajer proyek Anda.

Anda menjawab, "Itu tidak bisa dilakukan."

Mereka berkata, "Maka kita akan menemukan orang lain untuk melakukannya."

Anda berkata, "Oke, mungkin itu bisa dilakukan."

Dan kemudian menghabiskan jumlah X hari berikutnya .. minggu .. bulan .. mencoba mencari tahu. Sepanjang proses, Anda akan mencoba dan gagal, dan mencoba dan gagal. Kita semua melakukan ini. Jawaban sebenarnya adalah ada dua jenis programmer, yang berkomentar dan yang tidak.

1) Mereka yang melakukannya membuat pekerjaan mereka lebih mudah dengan mendokumentasikan referensi di masa mendatang, mengomentari kegagalan rutin yang tidak berhasil (baunya tidak menghapus mereka setelah menemukan yang berfungsi.), Atau memecah kode dengan komentar memformat ke semoga membuatnya lebih mudah dibaca atau dimengerti. Serius, saya tidak bisa menyalahkan mereka. Tetapi pada akhirnya, mereka patah dan kemudian Anda memilikinya: // dammit this code sucks! swear! curse! i hate it! i am going to write something here to vent my anger!!!!

2) Mereka yang tidak berpura-pura menjadi pahlawan super, atau tinggal di gua . Mereka hanya mengabaikan orang yang ceroboh terhadap orang lain, diri mereka sendiri, dan tidak peduli dengan kode itu, atau apa artinya itu nanti.

Sekarang jangan salah paham .. variabel dan fungsi self-documenting dapat menghindari ini sepenuhnya .. dan percayalah padaku Anda tidak akan pernah bisa melakukan pembersihan kode yang cukup. Tetapi kebenaran sederhananya adalah selama Anda menyimpan cadangan, Anda dapat [~ # ~] selalu [~ # ~] menghapus komentar.

1
Talvi Watia

Ada perbedaan mendasar yang besar antara komentar dan kode: komentar adalah cara bagi orang untuk menyampaikan ide kepada orang lain, sedangkan kode terutama ditujukan untuk komputer. Ada banyak aspek dalam "kode" yang juga hanya untuk manusia, seperti penamaan dan lekukan. Tetapi komentar ditulis khusus untuk manusia, oleh manusia.

Karena itu, menulis komentar sama sulitnya dengan komunikasi manusia tertulis! Penulis harus memiliki konsepsi yang jelas tentang siapa penontonnya, dan jenis teks apa yang akan mereka butuhkan. Bagaimana Anda bisa tahu siapa yang akan membaca komentar Anda dalam sepuluh, dua puluh tahun? Bagaimana jika orang tersebut berasal dari budaya yang sama sekali berbeda? Dll. Saya harap semua orang mengerti ini.

Bahkan di dalam budaya homogen kecil tempat saya tinggal, sangat sulit untuk mengkomunikasikan gagasan kepada orang lain. Komunikasi manusia biasanya gagal, kecuali karena kecelakaan.

1
user15127

Saya berpendapat bahwa tidak menggunakan beberapa komentar dalam kode Anda adalah bau kode. Sementara saya setuju bahwa kode harus mendokumentasikan diri sendiri sebanyak mungkin, Anda mencapai titik tertentu di mana Anda akan melihat kode yang tidak masuk akal terlepas dari seberapa baik kode tersebut ditulis. Saya telah melihat beberapa kode dalam aplikasi bisnis di mana komentarnya cukup wajib karena:

  1. Anda perlu melakukan sesuatu berdasarkan kasus per kasus dan tidak ada logika yang baik untuk itu.
  2. Kode kemungkinan akan berubah dalam satu atau dua tahun ketika undang-undang diubah dan Anda ingin menemukannya lagi dengan cepat.
  3. Seseorang mengedit kode di masa lalu karena mereka tidak mengerti apa yang dilakukan kode.

Juga, panduan gaya perusahaan mungkin memberi tahu Anda untuk melakukan sesuatu dengan cara tertentu - jika mereka mengatakan bahwa Anda harus memiliki komentar yang menguraikan apa yang dilakukan oleh blok kode dalam suatu fungsi, maka sertakan komentar tersebut.

1
rjzii

Saya harus setuju dengan rekan kerja Anda. Saya selalu mengatakan bahwa jika saya berkomentar kode saya, itu berarti bahwa saya khawatir bahwa I tidak akan dapat mengetahui milik saya sendiri kode di masa mendatang. Ini pertanda buruk.

Satu-satunya alasan saya menaburkan komentar ke dalam kode adalah untuk memanggil sesuatu yang tampaknya tidak masuk akal.

Komentar itu biasanya berupa sesuatu seperti:

//xxx what the heck is this doing??

atau

// removed in version 2.0, but back for 2.1, now I'm taking out again
0
Ken

Inilah aturan praktis saya:

  • Tulis kodenya dan simpan ringkasan singkat kodenya dalam dokumen terpisah.
  • Biarkan kode sendiri selama beberapa hari untuk mengerjakan sesuatu yang lain.
  • Kembali ke kode. Jika Anda tidak dapat segera memahami apa yang seharusnya dilakukan, tambahkan ringkasan ke file sumber.
0
Maxpm

Ajari rekan kerja Anda tentang teknik Literate Programming .

0
SK-logic

Pemberian komentar kode, jika berlaku, unit argumen fungsi dan pengembalian, bidang struktur, bahkan variabel lokal bisa sangat berguna. Ingat Pengorbit Mars!

0
dmuir

Tidak, komentar bukan bau kode, itu hanya alat yang bisa disalahgunakan.

Contoh baik komentar:

// Aku pikir ini dalam cm. Investigasi lebih lanjut diperlukan!

// Ini cara cerdas untuk melakukan X

// Daftar dijamin tidak kosong di sini

0
Andres F.

Namun kode yang tidak dapat dipahami sama sekali itu adalah kode yang lebih besar bau kode ...

Tolong beri saya kode bersih untuk dikerjakan
jika itu bukan pilihan, saya lebih suka memiliki kode "kotor" dengan komentar
daripada kode kotor tanpa komentar.

0
Ian

Sebagian besar kata-kata telah dikeluarkan dari mulutku. Tapi saya kira untuk merangkum semuanya: inti dari komentar adalah untuk memberikan deskripsi/penjelasan tingkat tinggi tentang apa yang dilakukan kode.

Selain itu, berikut adalah beberapa contoh bagaimana saya menggunakan komentar:

  • sebagai judul, untuk menunjukkan tujuan umum bagian kode
  • untuk mencatat di mana saya telah menulis kode dari dan karenanya menghindari plagiarisme
  • kadang-kadang di ujung blok, untuk mengingatkan blok apa yang menjadi tujuan mereka
  • untuk menunjukkan bahwa kode yang mungkin terlihat mencurigakan adalah yang dimaksudkan (mis. saat-saat ganjil saat sakelar beralih)
  • untuk menjelaskan matematika di balik suatu algoritma
0
Stewart

Tidak ada yang mengatakan ini sejauh ini di utas ini, jadi saya akan:

Ketikkan nama, nama variabel, nama fungsi, nama metode, dan komentar hanyalah metadata tentang kode Anda, dan tidak ada hubungannya dengan kode mesin yang dihasilkan oleh kompiler (kecuali nama simbol yang diekspor dan debug tentu saja).

Nama jenis dan nama variabel adalah kata benda Anda, nama fungsi dan metode adalah kata kerja Anda, dengan ini Anda menggambarkan langkah-langkah yang harus dilakukan. Komentar untuk yang lainnya.

Beberapa contoh:

double temperature; // In Kelvins.


/**
 * Returns true if ray hits the triangle
 */
bool castRayOnTriangle(Triangle t, Ray r)
{
    //...
    if (determinant == 0)
    {
        /* The ray and the triangle are parallel, no intersection possible.*/
        return false;
    }
    //...
}


/* X algorithm. Visit http://en.wikipedia.org/... for details.*/
<implementation of something difficult to understand for the layman algorithm. >

Komentar dapat menjadi usang, jika tidak diperbarui, tetapi nama variabel dan fungsi dapat menjadi usang juga. Baru-baru ini saya menemukan bidang bufPtr dalam struktur C, yang tidak ada hubungannya dengan buffer atau pointer. Dan saya melihat fungsi inflateBuffer yang tidak mendekompres data yang kempes tetapi file GZIP lengkap ... Ini sama menjengkelkannya dengan komentar yang sudah ketinggalan zaman.

0
Calmarius

Sepertinya tidak terlalu banyak jawaban yang mempertimbangkan pemrograman dalam tim. Saya seorang pengembang senior dan saya cenderung menulis komentar yang bertujuan menjelaskan apa yang sebenarnya mudah bagi saya untuk dipahami.

Saya melihatnya sebagai bentuk komunikasi atau pendidikan tim anumerta. Saya mendorong tim untuk melihat-lihat kode yang mereka gunakan, tetapi mungkin belum menulis untuk memahaminya dengan lebih baik.

Beberapa contoh baru mulai minggu ini (kode PHP):

//Pattern for finding jpeg photos
//Case insensitive pattern for jpg and jpeg
const PATTERN_PHOTO = "*.{[jJ][pP][gG],[jJ][pP][eE][gG]}";

Saya berharap nama PATTERN_PHOTO akan membantu nanti dalam kode untuk menjelaskan apa fungsinya, tetapi tanpa komentar seberapa jelaskah bagi pengembang junior apa pola spesifik ini?

Set kode yang sama:

//Ignore . and .. directories in Linux
if($file != "." && $file != "..")

Ada harapan bahwa pengembang kami tahu PHP, tetapi mereka tidak memahami OS Linux yang kami gunakan untuk hosting.

Jadi, saya menemukan komentar ini untuk benar-benar meningkatkan efisiensi tim kami secara keseluruhan untuk waktu yang sangat singkat untuk menulisnya.

  • Ada sedikit kasus orang menulis ulang kode hanya karena mereka tidak mengerti cara kerjanya. "Aku tidak mengerti bagaimana melakukan apa yang seharusnya, jadi aku memperbaikinya." Serius, saya harus berurusan dengan ini sebelumnya.
  • Ada lebih sedikit pertanyaan yang diajukan tentang masing-masing potongan kode. Menjawab pertanyaan sekali saja, biasanya membutuhkan mencari kode dan waktu bagi saya untuk membiasakan diri dengan itu. Dan kadang-kadang saya akan mendapatkan pertanyaan yang sama dari lebih dari satu minggu orang terpisah. (Ya, itu akan pada hal-hal sesederhana contoh di atas)
  • Pengembang lain didorong dan dibimbing untuk belajar sendiri. Saya berharap jika mereka menemukan //Ignore . and .. directories in Linux mereka kemungkinan akan naik ke Google dan tiba-tiba akan mengerti Linux sedikit lebih baik.
0
Chris