“Komentar adalah bau kode” [ditutup]

100

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?

Fishtoaster
sumber
44
Saya akan menjawab semua jawaban yang mengatakan "tidak".
Nicole
2
@Renesis Itulah bau ketuhanan.
ixtmixilix
107
Rekan kerja Anda membuat generalisasi menyeluruh, yang secara otomatis berarti dia salah. :)
Alex Feinman
5
@Mongus, saya tidak setuju. Komentar dalam contoh Anda buruk bukan karena mereka adalah komentar, tetapi karena mereka TERLALU dekat dengan kode yang kemudian berubah. Mereka harus mengatakan MENGAPA dan bukan APA .
5
@ Alex, bukankah itu generalisasi, yang karena itu salah (mengakibatkan dia tidak salah pula)?

Jawaban:

167

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

Thomas Owens
sumber
8
Saya setuju dengan jawaban ini vis a vis komentar, tapi saya juga melihatnya dikutip sebagai alasan kurangnya dokumentasi, yang salah. Membaca kode kadang-kadang menyebalkan. Anda tidak harus melihat kode untuk metode untuk mencari tahu apa metode itu. Anda harus bisa mengetahuinya dari nama dan mendapatkan lebih banyak detail dari dokumen. Saat membaca kode, Anda sering harus beralih dari kelas ke kelas, dan file ke file. Ini terutama masalah dalam bahasa dinamis, di mana menulis IDE yang dapat menangani semua ini adalah non-sepele.
davidtbernal
1
Ngomong-ngomong, kadang-kadang Anda juga harus mengomentari BAGAIMANA jika rumit (khususnya jika dioptimalkan atau jenis operasi non-sepele lainnya). Jika saya harus menghabiskan lebih dari 5 menit membaca satu blok kode untuk memahami apa yang dilakukannya, bisa sangat membuat frustasi ...
Khelben
3
"Hanya jika komentar menjelaskan apa yang dilakukan kode." Atau jika komentar tersebut menggambarkan apa yang digunakan kode; kode telah berubah tetapi komentar belum.
Bruce Alderman
1
Bagaimana Anda menguji apakah komentar Anda benar? Mengapa tidak menulis komentar Anda sebagai ujian? Setiap pengelola masa depan dapat menggunakan tes ini sebagai dokumentasi yang dapat diverifikasi untuk kode tersebut. Jika komentar itu ada hubungannya dengan eksekusi kode, maka itu sesuatu / harus / bisa dipastikan. Jika komentar tidak ada hubungannya dengan eksekusi kode, lalu apa yang dilakukannya dalam kode di mana hanya programmer yang akan melihat?
flamingpenguin
2
@ back2dos, jika Anda sering muntah ketika membaca kode orang lain, saya senang kami tidak berbagi kantor ...
110

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

Rekan kerja Anda tidak cukup berpengalaman, jelas.

Paul Nathan
sumber
16
Saya penasaran untuk melihat "kode nama baik, sangat bersih, tidak diomortasikan" yang sulit untuk diikuti. Setiap kode yang akan saya klasifikasikan seperti itu sangat mudah diikuti. Saya jelas tidak akan bertindak sejauh "Rekan kerja Anda tidak cukup berpengalaman, jelas".
Liggy
8
@ Liggy: Saya akan. Ini adalah algoritma penelitian, bukan aplikasi lini bisnis.
Paul Nathan
9
Saya pernah memiliki sepotong kode di mana Anda harus mengisi bidang dalam objek kolom basis data (pihak ke-3) dalam urutan "salah" (ditentukan oleh "logika" proses dan standar pengkodean kami) - lakukan sesuai urutan yang kami biasanya digunakan dan itu akan crash. Tidak ada jumlah membaca kode yang bisa memberi tahu Anda hal ini sehingga secara positif, mutlak, harus memiliki komentar - dan itu bukan bau, setidaknya tidak dalam kode yang kami kontrol (yang merupakan garis bawah). Kurangnya komentar yang lengkap dan sama sekali berbau seperti komentar buruk.
Murph
29
Matematika, matematika, matematika. Tidak semua kode menerapkan lem IoC yang sepele dan 'harga * kuantitas'. Matematika kompleks tidak dapat dibuat secara ajaib untuk menjelaskan sendiri.
bmargulies
4
@Liggy, kode yang mengimplementasikan struktur data kompleks dapat benar-benar tidak dapat dipahami tanpa dokumentasi yang luas.
75

Komentar harus menjelaskan mengapa, bukan bagaimana.

Howketik 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)
Sam Saffron
sumber
26
Saya setuju dengan bagian mengapa tidak bagaimana, dan refactoring Anda berfungsi dalam contoh ini, tetapi dengan kode yang lebih kompleks, tidak ada jumlah variabel / fungsi penggantian nama / refactoring akan membuatnya masuk akal, dan komentar masih akan diperlukan di sana.
GSto
3
Contoh yang bagus, tetapi mengapa sistem bekerja dengan sen dibandingkan dengan dolar? Pertanyaan itu menjadi relevan dalam sistem keuangan di mana Anda mungkin melihat mata uang pecahan ikut bermain.
rjzii
3
@Mulai nama fungsi harus mengatakan apa fungsinya.
Alb
3
@ GSto, saya tidak bisa tidak setuju lagi. Jika kodenya rumit, maka harus dipecah menjadi metode / fungsi yang lebih kecil dengan nama yang sesuai yang menggambarkan tindakan.
CaffGeek
1
Anda berasumsi, bahwa Anda memiliki kendali penuh atas basis kode.
LennyProgrammers
32

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

Komentar obsesif itu buruk dan sakit kepala, dan komentar bukan pengganti metode, kelas, variabel, dll. Namun, kadang-kadang mengatakan mengapa sesuatu itu bisa sangat berharga bagi idiot miskin yang harus menjaga kode dalam enam bulan - terutama ketika si idiot itu berakhir jadi 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.

BlairHippo
sumber
7
+1 untuk komentar yang bagus. Tidak ada jumlah kode yang dapat mengatakan "Jika ini terjadi, seseorang telah bermain-main dengan definisi database".
DistantEcho
9
@Niphra, well, kita bisa melempar SomebodyScrewedAroundWithDatabaseException...
@ Thorbjørn +1, Jika kodenya tahu apa yang salah, laporkan dengan baik. Pelanggan yang mendukung teknologi mungkin dapat memuat ulang DB mereka, dan menghindari panggilan layanan.
Tim Williscroft
@Tim, karena pelanggan mungkin melihat ini, penamaan yang lebih netral mungkin sesuai.
3
Tentu, ingat: jangan pernah menggunakan nama konyol. Pelanggan akan selalu melihatnya.
Tim Williscroft
29

Idealnya, kode harus dikodekan dengan sangat baik sehingga harus bersifat eksplikatif 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 dikelola / disejajarkan), berkomentar bahkan lebih tidak berguna.

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

Lorenzo
sumber
2
Konvensi penamaan yang baik dan kode yang terstruktur dengan baik akan membantu Anda mengurangi kebutuhan komentar. Jangan lupa bahwa setiap baris komentar yang Anda tambahkan itu adalah baris baru untuk dijaga !!
Gabriel Mongeon
81
Saya benci ketika orang menggunakan contoh kedua itu dalam pertanyaan Anda. } //end whilehanya berarti awal dari loop sementara begitu jauh, Anda bahkan tidak bisa melihatnya, dan tidak ada petunjuk bahwa kode yang Anda lihat adalah dalam satu lingkaran. Refactoring berat harus lebih disukai daripada komentar tentang bagaimana kode terstruktur.
Carson Myers
4
@Carson: sementara menjaga blok tetap pendek adalah aturan yang terkenal, itu tidak berarti bahwa kita selalu dapat menerapkannya.
Wizard79
4
@Carson: Salah satu proyek yang saya kerjakan memiliki ulasan kode yang tidak mencukupi, yang mengarah pada kumpulan JSP dengan kompleksitas siklus "OMFG JUST MEMBUNUH DIRI SENDIRI." Refactoring hal-hal berdarah merupakan hari kerja yang perlu dihabiskan di tempat lain. Mereka } // end whilecomments dapat menjadi penyelamat.
BlairHippo
11
@BlairHippo: "Bau kode [A] adalah gejala apa pun dalam kode sumber program yang mungkin mengindikasikan masalah yang lebih dalam". Tentu saja komentarnya adalah penyelamat hidup, tetapi loop-OMGWTF adalah "masalah yang lebih dalam" yang disebutkan di atas dan kebutuhan penyelamat adalah indikator yang jelas;)
back2dos
26

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

Harap ingat 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 proses, jadi satu-satunya masalah negatif yang perlu dipertimbangkan adalah pemeliharaan.

Tagihan
sumber
8
Saya pikir "anti-pola" adalah yang baru "dianggap berbahaya". Bau kode hanyalah sesuatu yang perlu diperiksa lebih dekat untuk kemungkinan pembersihan.
Jeffrey Hantin
1
Saya tidak setuju bahwa anti-pola juga memenuhi syarat. Mereka berdua terbiasa seperti itu dengan anti-pola yang digunakan daripada bau ketika desainnya cukup rumit sehingga jelas merupakan pilihan yang disengaja. Dalam kedua kasus saya tidak setuju dengan konsep bahwa ada sumber mutlak yang benar pada hal-hal ini.
Bill
4
+1 untuk "Refactoring semuanya sampai anak TK dapat memahaminya, mungkin bukan penggunaan waktu Anda secara efisien, dan mungkin tidak akan berkinerja sebaik versi yang lebih ringkas."
Earlz
23

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
pengguna281377
sumber
function prime_extjs_uploadform () {response.contentType = 'text / html'; render '{"success": true}'; } prime_extjs_uploadform ();
DrPizza
23

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 itu!

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

Perhatikan bahwa CodeSmell adalah petunjuk bahwa sesuatu mungkin salah, bukan kepastian. Sebuah 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 hanyalah tanda 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:

Rasmus Faber
sumber
2
Saya terkejut bahwa butuh 2 bulan untuk jawaban ini muncul. Ini menunjukkan betapa meluasnya kesalahpahaman istilah itu.
Paul Butcher
Penegasan kasus umum masih salah. Anda tidak mengatakan, "Saya melihat kode komentar. Itu pertanda buruk."
Stuart P. Bentley
1
@Stuart: Anda sedang melihat dua potongan kode, keduanya dengan tingkat komentar yang sesuai. (Masalah ini bukan tentang jumlah komentar yang tepat, ini tentang bagaimana Anda menilai kode berdasarkan jumlah komentar.) Yang satu tidak memiliki komentar, yang lain memiliki banyak. Mana yang Anda lihat lebih dekat? - Komentar adalah tanda bahwa kode itu rumit dan halus sehingga lebih cenderung memiliki masalah.
David Schwartz
Ini jawaban yang benar.
vidstige
21

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.

Program Lenny
sumber
8
+1 Kepada pengembang mana pun yang belum mengerjakan proyek tunggal cukup lama untuk mengalami ini, percayalah itu akan terjadi. Setiap kali saya mempelajari ini dengan cara yang sulit dan harus mempelajari kembali kode saya sendiri, saya tidak membiarkan diri saya melakukan kesalahan yang sama dua kali dan berkomentar sebelum saya beralih ke sesuatu yang lain.
Nicole
Tidak, Anda harus membayangkan seorang psikopat yang tahu di mana Anda tinggal: apakah mereka akan senang mempertahankan kode Anda?
Richard
4
Saya secara teratur menjadi psikopat ketika saya melihat kode yang tidak dapat dibaca.
LennyProgrammers
3
5 tahun? Lebih seperti 5 menit. ;)
Alex Feinman
11

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 saja 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 untuk 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.

Tom Wijsman
sumber
1
Inilah yang saya lakukan. Jika Anda pikir Anda perlu komentar, saya sungguh-sungguh merekomendasikan mencoba ini sebagai pengganti.
bzlm
10

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.

Brandon
sumber
10
// 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.
Zzz
sumber
Ah, permohonan tulus untuk masa depan diri.
Anthony Pegram
8

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. 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 konten tekstual kode Anda, komentar harus mengikuti prinsip penulisan yang baik selain ditulis dengan jelas.

Untuk menulis komentar yang baik, Anda harus melakukan yang terbaik untuk mendokumentasikan tujuan kode (mengapa, bukan bagaimana) 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.

Scott Dorman
sumber
1
Komentar dapat menjadi basi, tetapi itu berlaku untuk semua yang tidak diverifikasi oleh kompiler atau tes unit, seperti arti dari kelas, fungsi dan nama variabel.
LennyProgrammers
@ Lenny222: Ya, komentar bisa menjadi basi ... yang biasanya menunjukkan pemrogram yang malas. Jika komentar menjelaskan mengapa keputusan dibuat, mengapa kode menggunakan algoritma tertentu untuk perhitungan, atau menjelaskan bagaimana kode berfungsi, maka tidak ada alasan untuk komentar menjadi basi selain seseorang yang mengubah implementasi dan tidak memperbarui komentar yang sesuai. - yang setara dengan malas.
Scott Dorman
2
Saya setuju. Maksud saya adalah, ada risiko menjadi basi, ya. Tetapi ketika saya memiliki fungsi doBar () dan setelah 3 tahun itu tidak "melakukan bar", tetapi "melakukan bar dan foo kecuali pada hari Rabu" maka arti dari fungsi dapat menjadi basi juga. Dan nama variabel. Tapi saya harap tidak ada yang mengambil ini karena alasan untuk tidak memberikan fungsi dan variabel nama yang bermakna.
LennyProgrammers
6

Jika kode telah ditulis dengan cara tertentu untuk menghindari masalah yang ada di perpustakaan (baik perpustakaan pihak ketiga, atau perpustakaan yang disertakan 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.

kiamlaluno
sumber
6

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.

banyak sekali
sumber
Komentar semacam ini memberikan isyarat visual yang bagus sehingga Anda tidak perlu membaca setiap baris untuk menemukan awal bagian yang Anda cari. Seperti yang sering dikatakan kakek saya, "semuanya dalam jumlah sedang."
Blrfl
4

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.

mario
sumber
4

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. Sepertinya tidak terlalu jelas apa yang seharusnya dilakukan oleh kode . Tanpa komentar bagaimana Anda tahu jika hasilnya salah, atau mereka digunakan secara tidak benar?

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

Saya biasanya menemukan diri saya menulis komentar sebaris sebelum 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.

Danny Tuppeny
sumber
1
Tes unit sangat membantu untuk menentukan apakah hasilnya salah. Jika Anda membaca beberapa kode dan menganggapnya X ketika kenyataannya Y, maka mungkin kode tersebut tidak ditulis dengan cara yang cukup mudah dibaca. Saya tidak yakin apa yang Anda maksud tentang hasil yang digunakan secara tidak benar. Sebuah komentar tidak akan melindungi Anda dari seseorang yang menggunakan kode Anda dengan cara yang aneh.
Adam Lear
"Jika kamu membaca beberapa kode dan berpikir itu adalah X padahal kenyataannya itu Y" Bukan itu yang aku katakan. Saya berbicara tentang memahami apa yang dilakukan kode , tetapi tidak apa yang seharusnya dilakukan. Katakanlah Anda mencurigai adanya kesalahan satu per satu. Bagaimana Anda tahu bahwa kesalahan satu demi satu tidak ada dalam kode yang dikonsumsi atau bukan kode ini? Komentar menjelaskan maksud kode, yang sangat membantu melacak bug.
Danny Tuppeny
Di sisi lain, komentar mungkin hanya memberi tahu Anda apa yang seharusnya dilakukan kode pada saat komentar ditulis. Kode itu sendiri mungkin memberi tahu Anda apa yang seharusnya dilakukan sekarang. Komentar tidak dikompilasi. Anda tidak dapat menguji komentar. Mereka mungkin atau mungkin tidak benar.
Anthony Pegram
3

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-orang yang tidak akan pernah memberikan komentar, atau bahkan menulis sedikit bantuan untuk pengembang lain juga tidak enak. Saya kagum pada berapa banyak orang yang tidak akan menulis, 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.

MIA
sumber
3

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

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
Semut
sumber
Tetapi, bagaimana dengan zaman dan zaman sekarang ini, apakah Anda tidak menggunakan bahasa tingkat tinggi?
Ian
2
@Ian: Program ini adalah bootloader IBM-PC. Anda tidak dapat menulisnya selain dari perakitan, karena Anda memerlukan kontrol total di mana tepatnya program berada di RAM, di mana short terakhir muncul, dan beberapa perangkat keras menyela. Serius, ambil sendiri salinan NASM. Pasang, tulis ke sektor boot dari disket atau stik USB, dan boot. Meskipun Anda mungkin menemukan itu tidak berfungsi seperti yang diharapkan karena bug. Sekarang temukan bug ... Bagaimanapun juga, saya yakin bahwa dalam 20 tahun dari sekarang, orang akan menanyakan hal yang sama tentang Java yang tidak di-komentar.
Semut
Tentunya kode dapat ditulis dalam C atau C ++, dan biner dikumpulkan dari kode objek C dan beberapa alat eksternal.
kevin cline
Sayangnya tidak. Lihat halaman ini di CodeProject: codeproject.com/KB/tips/boot-loader.aspx - "bahasa tingkat tinggi tidak memiliki instruksi yang diperlukan". Tidak hanya itu, tetapi Anda hanya punya 512 byte untuk dimainkan dengan bootloader. Terkadang Anda hanya perlu langsung ke perangkat keras.
Semut
1
Saat mengkode perakitan, saya akan melakukan apa yang dilakukan orang lain - berkomentar setiap baris dengan apa yang dilakukannya. Baris yang dimaksud akan memiliki komentar "periksa apakah huruf adalah 0", karena kode menggunakan string diakhiri C-style 0. Dengan komentar di tempat, mudah untuk melihat bahwa kode melakukan cmp dengan 1, yang berarti terjebak di loop tak terbatas atau mencetak sampah hingga mencapai angka 1 acak dalam RAM. Saya mungkin juga telah menambahkan komentar tentang fakta bahwa string-0 dihentikan, yang tidak terlihat dari kode. Apakah ada yang namanya pengujian unit otomatis untuk coding perakitan?
Semut
2

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 sendiri adalah "ketika ragu, berkomentar". Saya lebih suka memiliki garis 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 cukup membantu menambahkan "peringatan" seperti "Hati-hati! Jika format input bukan ASCII, kode ini harus diubah!"

Khelben
sumber
Bisakah Anda menjelaskan apa yang Anda maksud dengan "komentar yang melanjutkan blok kode"?
Mark C
2

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.

Murph
sumber
2

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. Meskipun penamaan objek bisa basi, berbagai mekanisme manusia dan komputer kurang umpan balik membuatnya mudah untuk melupakan untuk menjaga komentar dan akibatnya komentar menjadi basi lebih cepat daripada kode aktif. Karena alasan itu, di mana suatu pilihan dimungkinkan, mengubah kode untuk membuatnya lebih jelas harus selalu lebih disukai daripada menjelaskan kode yang tidak jelas dengan komentar.

Alohci
sumber
+1 untuk menunjukkan bahwa kebiasaan komentar buruk dimulai dengan kelas pemrograman awal. -1 untuk menyimpulkan bahwa komentar hanyalah pilihan terakhir.
AShelly
1

Tentu saja komentar adalah bau kode ...

setiap programmer tahu kita semua pada 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, "Kalau begitu kita akan menemukan orang lain untuk melakukannya."

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

Dan kemudian menghabiskan jumlah X hari berikutnya .. minggu .. bulan .. mencoba untuk mencari tahu. Sepanjang proses, Anda akan mencoba dan gagal, dan mencoba dan gagal. Kita semua melakukan ini. Jawaban yang benar 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 agar mudah membuatnya lebih mudah dibaca atau dimengerti. Serius, saya tidak bisa menyalahkan mereka. Tetapi pada akhirnya, mereka patah dan kemudian Anda memiliki ini: // 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 hidup di gua . Mereka hanya mengabaikan orang yang ceroboh terhadap orang lain, diri mereka sendiri, dan tidak peduli dengan kode itu, atau apa artinya itu nantinya.

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

Talvi Watia
sumber
1
Menanggapi 1. Aroma sebenarnya dalam rutinitas yang dikomentari bukanlah menghapusnya segera ketika Anda memutuskan bahwa mereka mungkin buntu dan ingin mencoba sesuatu yang berbeda --- ini karena mereka harus tersedia dalam kontrol versi jika Anda memutuskan untuk mengunjungi mereka kembali .
Sharpie
1

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.

rjzii
sumber
1

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.

Oleh 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 ide kepada orang lain. Komunikasi manusia biasanya gagal, kecuali karena kecelakaan.

pengguna15127
sumber
0

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

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

Komentar-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
Ken
sumber
1
Atau, sebagai alternatif, komentar dapat mencerminkan fakta bahwa kode tersebut mengatasi algoritma yang kompleks di mana kode menjadi tidak jelas atau karena kode melakukan sesuatu yang aneh karena faktor-faktor di luar kendali Anda (misalnya berinteraksi dengan layanan eksternal).
Murph
Sangat benar. Ada alasan mengapa kode yang baik mungkin tidak jelas. Sebagian besar waktu meskipun kode membingungkan membingungkan karena ditulis dengan cara yang membingungkan.
Ken
Sepertinya Anda belum menulis kode untuk prosesor tertanam di mana Anda hanya memiliki 32k untuk dimainkan, dan hal-hal yang Anda lakukan tidak jelas. Komentar adalah penyelamat hidup.
cepat,
0

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

dmuir
sumber
Jauh lebih baik untuk membangun unit menjadi nama variabel, sehingga programmer yang buruk tidak harus mengingatnya. Alih-alih 'panjang ganda // dalam meter' katakan 'panjang ganda_m'. Yang terbaik dari semuanya adalah menggunakan bahasa yang lebih kuat, jadi Anda bisa mengatakan Panjang l; Kekuatan f; Torsi t = l * f; print (t.in (Torque.newtonMeter));
kevin cline
0

Inilah aturan praktis saya:

  • Tulis kode dan simpan ringkasan singkat kode 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.
Maxpm
sumber
0

Tidak, komentar bukan bau kode, mereka hanya alat yang dapat disalahgunakan.

Contoh dari komentar yang baik :

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

// Ini cara cerdas untuk melakukan X

// Daftar dijamin tidak kosong di sini

Andres F.
sumber
Yang ketiga adalah komentar buruk IMO. Mengapa tidak Assert(list.IsEmpty)?
CodesInChaos
@CodeInChaos IMO Assert(!list.isEmpty())tidak persis kontrak seperti dalam komentar ketiga, tetapi hanya perilaku (yaitu "membuang IllegalArgumentException jika argumen kosong") yang harus diuji unit seperti logika program lainnya. Perhatikan perbedaan halus dengan komentar, yang menyatakan kapan metode dapat digunakan, tetapi menentukan tidak ada perilaku jika prasyarat tidak terpenuhi. Bahkan lebih baik daripada komentar adalah untuk menegakkan kontrak waktu kompilasi. Tapi ini melebihi ruang lingkup jawabanku;)
Andres F.
Anda seharusnya tidak dapat berolahraga Assert, karena mereka menggambarkan hal-hal yang seharusnya tidak pernah terjadi, bahkan jika API publik menerima argumen yang tidak valid.
CodesInChaos
@CodeInChaos Saya menarik kembali pendapat saya. Inilah yang dikatakan Sunacle tentang pernyataan . Sepertinya Anda benar. Nah, Anda belajar sesuatu setiap hari!
Andres F.