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?
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?
Jawaban:
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.
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.
Komentar harus menjelaskan mengapa, bukan bagaimana.
How
ketik 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)
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.
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.
} //end while
hanya 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.
} // end while
comments dapat menjadi penyelamat.
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.
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
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.
EDIT: Saya baru saja meneliti dua artikel ini, yang menjelaskannya lebih baik daripada saya:
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.
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.
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.
// 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.
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.
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.
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.
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.
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.
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
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!"
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.
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.
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:
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.
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.
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
Pemberian komentar kode, jika berlaku, unit argumen fungsi dan pengembalian, struktur bidang, bahkan variabel lokal bisa sangat berguna. Ingat Pengorbit Mars!
Inilah aturan praktis saya:
Didik rekan kerja Anda tentang teknik Pemrograman Literate .
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
Assert(list.IsEmpty)
?
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;)
Assert
, karena mereka menggambarkan hal-hal yang seharusnya tidak pernah terjadi, bahkan jika API publik menerima argumen yang tidak valid.